.. _add-docs: Documentation ============= Documentation is important for your users and for yourself. The documentation is built using `Sphinx `_. Generally, a project will have a few types of documentation: * A ``README`` style overview, providing an quick introduction to the package (or the subdirectory in which it is included) (a base-level ``README.md`` file is :ref:`automatically generated by the cookiecutter `) * User guide-type documentation, which explains how and why to use the package. While it may contain code examples, it's typically more of a broad overview of package usage. For example, this page is user-guide-like documentation. A stub page for user-guide-like documentation is created in ``docs/source/getting_started.rst``. * API documentation, which explains how to use the code. This is often automatically generated from docstrings in the code. A stub page for API documentation is created in ``docs/source/api.rst``. The template ``docs/`` directory contains configuration files and initial stub pages for generating User Guide and API documentation using `Sphinx <(https://www.sphinx-doc.org>`_. .. _documentation-writing: Writing documentation for Sphinx -------------------------------- The cookiecutter creates three initial pages for your documentation, found in ``docs/source/``: * ``index.rst``: the 'home page', including a table of contents * ``getting_started.rst``: a stub page for user-guide-like documentation * ``api.rst``: a page for API documentation, using Sphinx's autosummary extension to automatically generate documentation from your code's docstrings, assumed to be `NumPy style docstrings `_ These files are written in `ReStructuredText format `_. Modify these as you see fit, and add any additional pages in this folder. See the `Sphinx User Guide `_ for help. .. _documentation-configuration: Configuring the documentation with Sphinx ----------------------------------------- The documentation is configured in the ``docs/source/conf.py`` file. This file contains settings for the documentation, such as the project name, version, and theme. You can also add extensions to the documentation. More information on configuring Sphinx can be found in the `Sphinx documentation `_. By default, the documentation is built using the MDAnalysis sphinx theme using the default template MDAKits logo and `favicon`_, and includes several useful extensions, e.g. to allow building of API docs from NumPy style docstrings. You can customise your documentation by: * **Add additional extensions and configuration options** - see the `Sphinx documentaiton `_. * **Changing the theme** by modifying the ``html_theme`` variable in ``docs/source/conf.py``. You could also add custom style sheets in the ``docs/source/_static/`` and/or template pages in ``docs/source/_templates/``; see the respective ``README.md`` files in those folders for more information. * **Changing the logo**: You can also change the logo by either modifying the ``html_logo`` variable or by replacing the ``_static/logo/mdakits-placeholder-logo.png`` file. (This path is relative to the ``docs/source`` directory; the full path, relative to the repository root, is ``docs/source/_static/logo/mdakits-placeholder-logo.png``.) Similarly, you can change the favicon by replacing the ``html_favicon`` variable or by replacing the ``_static/logo/mdakits-empty-favicon-template.svg`` file. You are welcome to either create an entirely custom logo and favicon or to use the provided templates. An ``mdakits-empty-logo-template.svg`` and ``mdakits-empty-favicon-template.svg`` are provided in the ``docs/source/_static/logo`` directory as templates for editing -- feel free to place your logo within the gears! .. _documentation-building: Building the documentation with Sphinx -------------------------------------- Building documentation requires different dependencies to you main package; an initial list of dependencies is provided in ``docs/requirements.yaml`` which can be used to create a new virtual environment or :ref:`be added to the current virtual environment `. If you documentaiton requires additional/different dependencies, include them here and in ``pyproject.toml``. The configuration file ``docs/Makefile`` and ``docs/make.bat`` are also provided to allow you to build your documentation. The documentation can be build by running the following command in the ``docs/`` directory: .. code-block:: bash $ cd docs $ make html This will build the documentation (as ``.html`` files) in a ``docs/_build/`` directory; you can now view these files to see your built documention. .. _documentation-hosting: Hosting documentation with ReadTheDocs -------------------------------------- If you selected the to 'include ReadTheDocs' when using the cookiecutter (the default option), you can now use it to automatically build and host your documentation. `ReadTheDocs `_ is an external service. To link it to your repository, first log in to ReadTheDocs using your GitHub account. Click ``Import a Project`` on the ReadTheDocs dashboard (your project should appear here once it has pushed to GitHub). After importing you project, ReadTheDocs will build your documentation, and it will now appear online with it's very own URL (likely at ``https://{repo_name}.readthedocs.io``)! We strongly recommend turning on building documentation for your pull requests to check and preview your docs. To do so: #. Go to the Admin tab #. Go to Advanced Settings #. Tick the "Build pull requests for this project" checkbox #. Scroll down and remember to click "Save"! A test build of the documentation will now be created and can be viewed for each PR. Further configuration can be done on from the ReadTheDocs dashboard or in the ``readthedocs.yaml`` file - see the `ReadTheDocs documentation `_.