Repository files navigation

This repository hosts the new developer documentation for Mautic on theRead the Docs platform. Whenever a PR is merged, changes are deployed immediately tohttps://mautic-developer.readthedocs.io/

If you're looking for the legacy developer documentation, please go tohttps://developer.mautic.org/ or theGitHub repository.

The aim is to move all aspects of the developer documentation to Read the Docs (with the exception of the REST API documentation).In the video below,@dennisameling explains how the documentation is currently structured and briefly touches upon current limitations.

For more background, the end goal, and if you want to help, please seethis issue. Thanks in advance.

Code samples get downloaded from GitHub to ensure that they're always up to date. If you want to add a new code sample, follow these two steps:

1. Create a file indocs/code_samples/ and add a permalink in there. Look at other files in that directory for examples. URLs should always start withhttps://raw.githubusercontent.com/... to ensure that Sphinx can download the file correctly.
2. In any documentation file, add aliteralinclude block to include the code, like so:

.. The link to this file is defined in docs/code_samples/helloworld_entity_world.py .. literalinclude:: ../code_samples_downloaded/Entity_World.php    :language: php

Tip: downloaded files get cached indocs/code_samples_downloaded to prevent overloading GitHub with download requests. If you change the URL to a file, simply remove the cached file fromdocs/code_samples_downloaded and Sphinx automatically re-downloads it.

• RST Syntax Cheatsheet
• Sphinx Demo
• Sphinx Syntax

The following provides instructions for how to build docs locally for visualization without pushing to the remote:

1. Install Python 3 for your OS if not already installed
2. Install Sphinxpip install sphinx
3. Install sphinx-rtd-themepip install sphinx-rtd-theme
4. CD into the docs directorycd [path to this repo]/docs
5. Runmake html
6. This generates HTML in docs/build/html. Setup a web server with the web root as docs/build/html or open docs/build/html/index.html in a browser.

If the build isn't working for some reason, here's some tips:

• Try running themake html command in the terminal:cd docs && make html. This command normally provides a lot of additional context.
• If the preview isn't working, click theesbonio section in the bottom right corner of the VS Code window. That rebuilds the docs and previews, and tells you if something is wrong.

Before pushing, run Vale and address suggestions and errors as applicable.

1. Installvale
2. vale .

You can automatically build changes to.rst files using a file watcher.

1. Go to Preferences -> Tools -> File Watchers -> + button -> custom
2. Configure the watcher as presented in the screenshot

Please consult Mautic'sstyle-guide before contributing to the documentation. Some rules get enforced through Vale.

As a quick reference, here's the list of headings Mautic uses:

H1: ############H2: ****************H3: ============H4: ----------------H5: ~~~~~~~~~~~~

Mautic's documentation usesreStructuredText, or.rst files. Luckily, there's converters available that help you convert.md to.rst files. Here's an example ofm2r - this converter also converts tables intolist-table directives properly.

pip install m2r# This creates a new file with the .rst extension:m2r my_markdown_file.md

Thanks goes to these wonderful people (emoji key):

Robert Parker 📖

Rahul Shinde 📖

Dennis Ameling 📖👀

Ife 📖

Balbinder Sumbria 📖

Hugo-Prossaird 📖

Randy Fay 📖

This project follows theall-contributors specification. Contributions of any kind welcome.