Writing examples#
The documentation generator used for PyDPF-Core is Sphinx. Most of the documents are written in reStructuredText. Some parts of the documentation, like the examples, use a mix of reStructuredText and Python, thanks to Sphinx-Gallery.
The examples section of the documentation showcases different
capabilities of PyDPF-Core. Each example (grouped into folders of related examples)
is a standalone Python script. Despite being *.py files, they are written in a mix
of reStructuredText and Python. This is possible thanks to the Sphinx-Gallery
Sphinx extension.
Documentarians writing new examples are encouraged to familiarize themselves with
structuring Python scripts for Sphinx-Gallery.
Once the .py file for a new example is properly set up, Sphinx-Gallery automatically
generates Sphinx reStructuredText files from it. The rendering of the resulting reST will provide
users with .ipynb (Jupyter notebook) and .py files for each example, which users can download.
Finally, here are some tips for writing examples:
Start the example with an explanation of the main topic. Try to use as many relevant keywords as possible in this section to optimize for Search Engine Optimization.
Include an explanation with each code cell. The explanations should be included before, not after, the corresponding code.
The examples are built with the documentation. As part of the build process, screenshots of rendered graphics are inserted in the document. You do not need to include the screenshots yourself.
When creating a new example folder, ensure a
README.txtfile is also included. This file should contain reST to be used as the header for the index page corresponding to the subsection for these examples in the generated documentation.