.. _documenting-abipy: Documenting AbiPy ================= .. contents:: :backlinks: top Organization of documentation ----------------------------- The AbiPy documentation is generated from ReStructured Text using the Sphinx_ documentation generation tool. The documentation sources are in the :file:`~/docs/` directory in the repository. Major items: * index.rst - the top level include document for AbiPy docs * api - placeholders to automatically generate the api documentation * scripts - documentation for scripts * flow_gallery/gallery - automatically generated by sphinx-gallery * workflows - Documentation about Abinit flows/works/tasks and TaskManager * README.rst - the present file * conf.py - the sphinx configuration file * _static - used by the sphinx build system The main entry point is :file:`docs/index.rst`, which pulls in the files for the users guide, developers guide, api reference. The actual ReStructured Text files for the APIs of the subpackages, for the scripts and for the workflows (resp.) are kept in :file:`docs/api`, :file:`docs/scripts` and :file:`docs/workflows` (resp.). Additional files can be added to the various guides by including their base file name (the ``.rst`` extension is not necessary) in the table of contents. It is also possible to include other documents through the use of an include statement, such as:: .. include:: ../../TODO The output produced by Sphinx can be configured by editing the :file:`conf.py` file located in the :file:`docs/`. Before building the documentation, you need to install the sphinx extensions listed in :file:`abipy/docs/requirements.txt` with:: pip install -r abipy/docs/requirements.txt To build the HTML documentation, install sphinx then type ``make`` that will execute:: sphinx-build -b html -d _build/doctrees . _build/html Remember to issue:: export READTHEDOCS=1 before running ``make`` to activate the generation of the thumbnails in :file:`abipy/examples/flows`. The documentation is produced in :file:`_build/html`. Use:: open _build/html/index.html to open the homepage in your browser. You can run ``make help`` to see information on all possible make targets. Use:: ./ghp_import.py _build/html/ -n -p to deploy to gh-pages (only for project leader). .. _formatting-abipy-docs: Formatting ---------- The Sphinx website contains plenty of documentation_ concerning ReST markup and working with Sphinx in general. Here are a few additional things to keep in mind: * Please familiarize yourself with the Sphinx directives for `inline markup`_. Abipy's documentation makes heavy use of cross-referencing and other semantic markup. Several aliases are defined in :file:`abipy/docs/links.rst` and are automatically included in each ``rst`` file via `rst_epilog `_ * Mathematical expressions can be rendered with `mathjax `_ in html. For example: ``:math:`\sin(x_n^2)``` yields: :math:`\sin(x_n^2)`, and:: .. math:: \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}} yields: .. math:: \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}} * Bibtex citations are supported via the `sphinxcontrib-bibtex extension `_ The bibtext entries are declared in the :file:`abipy/docs/refs.bib` file. For example:: See :cite:`Gonze2016` for a brief description of recent developments in ABINIT. yelds: See :cite:`Gonze2016` for a brief description of recent developments in ABINIT. To add a new bibtex entry to the database, please use the :program:`doi2bibtex` tool provided by the `betterbib package `_:: doi2bibtex https://doi.org/10.1103/PhysRevB.33.7017 >> refs.bib then change the bibtex identifier (use the name of the first author and the publication year). * Interactive ipython_ sessions can be illustrated in the documentation using the following directive:: .. sourcecode:: ipython In [69]: lines = plot([1, 2, 3]) which would yield: .. sourcecode:: ipython In [69]: lines = plot([1, 2, 3]) * Use the *note* and *warning* directives, sparingly, to draw attention to important comments:: .. note:: Here is a note yields: .. note:: here is a note also: .. warning:: here is a warning * Use the *deprecated* directive when appropriate:: .. deprecated:: 0.98 This feature is obsolete, use something else. yields: .. deprecated:: 0.98 This feature is obsolete, use something else. * Use the *versionadded* and *versionchanged* directives, which have similar syntax to the *deprecated* role:: .. versionadded:: 0.2 The transforms have been completely revamped. .. versionadded:: 0.2 The transforms have been completely revamped. * The autodoc extension will handle index entries for the API, but additional entries in the index need to be explicitly added. .. _documentation: http://www.sphinx-doc.org/en/master/ .. _`inline markup`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html?highlight=inline#inline-markup Docstrings ---------- In addition to the aforementioned formatting suggestions: * Docstrings are written following the `Google Python Style Guide `_. We use the `napoleon `_ extension to convert Google style docstrings to reStructuredText before Sphinx attempts to parse them. Dynamically generated figures ----------------------------- Figures can be automatically generated from scripts and included in the docs. It is not necessary to explicitly save the figure in the script, this will be done automatically at build time to ensure that the code that is included runs and produces the advertised figure. Any plots specific to the documentation should be added to the :file:`examples/plot/` directory and committed to git. `sphinx-gallery `_