https://github.com/mautic/developer-documentation-new
New developer documentation on Read the Docs
https://github.com/mautic/developer-documentation-new
documentation hacktoberfest mautic read-the-docs sphinx
Last synced: 3 months ago
JSON representation
New developer documentation on Read the Docs
- Host: GitHub
- URL: https://github.com/mautic/developer-documentation-new
- Owner: mautic
- Created: 2021-03-31T09:54:40.000Z (about 4 years ago)
- Default Branch: 5.x
- Last Pushed: 2024-10-26T15:56:21.000Z (7 months ago)
- Last Synced: 2024-10-29T18:48:28.794Z (7 months ago)
- Topics: documentation, hacktoberfest, mautic, read-the-docs, sphinx
- Homepage: https://mautic-developer.readthedocs.io
- Size: 3.77 MB
- Stars: 6
- Watchers: 6
- Forks: 27
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[![Documentation Status][RTD badge URL]][RTD URL]
[](#contributors-)
[](https://gitpod.io/#https://github.com/mautic/developer-documentation-new)
# Mautic developer documentation (new)
This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://mautic-developer.readthedocs.io/
If you're looking for the legacy developer documentation, please go to https://developer.mautic.org/ or the [GitHub repository][Legacy dev docs].
## Migration of developer docs to 'Read the Docs'
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][dennisameling GH profile] 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 see [this issue][New docs background and goals]. Thanks in advance.
[![Link to YouTube video with explanation of the current developer documentation structure][YouTube video image]][YouTube video URL]
## 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:
1. 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.
2. 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
- [RST Syntax Cheatsheet][RST Cheatsheet]
- [Sphinx Demo][Sphinx Demo]
- [Sphinx Syntax][Sphinx Template]
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 Sphinx `pip install sphinx`
3. Install sphinx-rtd-theme `pip install sphinx-rtd-theme`
4. CD into the docs directory `cd [path to this repo]/docs`
5. Run `make 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.
## 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.
1. Install [`vale`][Vale]
2. `vale .`
### PhpStorm & PyCharm file watcher
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
### Style guide
Please consult Mautic's [`style-guide`][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
```
[ReadTheDocs]:
[Legacy dev docs]:
[dennisameling GH profile]:
[New docs background and goals]:
[YouTube video image]:
[YouTube video URL]:
[RTD badge URL]:
[RTD URL]:
[RST Cheatsheet]:
[Sphinx Template]:
[Sphinx Demo]:
[Vale]:
[Style Guide]:
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Robert Parker
📖
Rahul Shinde
📖
Dennis Ameling
📖 👀
Ife
📖
Balbinder Sumbria
📖
Hugo-Prossaird
📖
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome.