Mautic developer documentation (new)

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

If you're looking for our legacy developer documentation, please go to https://developer.mautic.org/ or the GitHub repository.

Migration of developer docs to Read the Docs

We aim 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 we're running into.

For more background, our end goal, and to let us know if you want to help, please check out this issue. Thanks in advance!

Adding a code sample

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:

Create a file in docs/code_samples/ and add a permalink in there. Look at other files in that directory for examples. URLs should always start with https://raw.githubusercontent.com/... to ensure that Sphinx can download the file correctly.
In any documentation file, add a literalinclude 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 in docs/code_samples_downloaded to prevent overloading GitHub with download requests. If you change the URL to a file, simply remove the cached file from docs/code_samples_downloaded and Sphinx automatically re-downloads it.

Build documentation locally

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

Install Python 3 for your OS if not already installed
Install Sphinx pip install sphinx
Install sphinx-rtd-theme pip install sphinx-rtd-theme
CD into the docs directory cd [path to this repo]/docs
Run make html
This will generate 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.

Troubleshooting

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

Try running the make 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 the esbonio section in the bottom right corner of the VS Code window. That rebuilds the docs and previews, and tells you if something is wrong.

Vale

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

Install vale
vale .

PhpStorm/PyCharm File Watcher

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

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

Style guide

Please consult Mautic's style-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: ~~~~~~~~~~~~

Converting markdown to reStructuredText

Mautic's documentation uses reStructuredText, or .rst files. Luckily, there's converters available that help you convert .md to .rst files. Here's an example of m2r - this converter also converts tables into list-table directives properly.

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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Robert Parker}
📖

_{Rahul Shinde}
📖

_{Dennis Ameling}
📖 👀

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

thmclellan/developer-documentation-new