How to create documentation/guides

This is a simple guide on how you can write documentation and guides for users, developers and sysadmins.

Note

Devilry is truly open, not just Open Source, but we also try to keep all issues, suggestions and plans in the open. This means that your suggestions, bugs, problems, etc. is handled in the open, and readable by anyone.

Warning

DO NOT post sensitive information in the documentation/guides.

How do we document the code?

For Devilry we use the Sphinx extension Napoleon <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/> which uses the Google Python Style Guide as documentation syntax. Napoleon is a pre-processor that parses the docstrings to reStructucteredText <http://docutils.sourceforge.net/rst.html> before sphinx parses the documentation.

How to write guides

Let’s take the three main documentation/guide categories: user, developer and sysadmin as examples for the index.rst file.

Here’s an example of the root index.rst file containing a link to the index of the three categories. This is a portion of the index file taken from the actual Devilry docs:

####################################
Welcome to the Devilry documentation
####################################


Table of contents
=================

.. toctree::
    :maxdepth: 1

    user/index
    sysadmin/index
    developer/index
    create_docs_how_to

Let’s use the user guide as an example of how you structure the documentation/guides.

The user folder contains it’s own index.rst file, which again refers to other .rst files in the same folder. Here’s an example of the user index.rst file looks like:

==========================
Devilry user documentation
==========================


Getting started
---------------
We recommend that you start with a quick look at :ref:`commonconcepts`.
This avoids confusion with a few special terms that Devilry uses to allow
it to be used in many different settings. When you have skimmed over the concepts,
you can continue with the other Topic guides below.


Common for all roles
--------------------

.. toctree::
   :maxdepth: 1

   commonconcepts
   email
   changelog_overview


Student
-------

.. toctree::
   :maxdepth: 1

   student
   student_groups


Examiner/Corrector
------------------

.. toctree::
   :maxdepth: 1

   examiner


Subject/Course administrator
----------------------------
.. note::
    For users managing one or more courses.

.. toctree::
   :maxdepth: 1

   subjectadmin
   subjectadmindeadlines
   subjectadmin_groups
   subjectadmin_examiner
   subjectadmin_qualifiesforexam


Node/Department admin
---------------------
.. note::
    For users managing a Node containing multiple courses.

.. toctree::
   :maxdepth: 1

   nodeadmin
   nodeadmin-finditems
   nodeadmin_qualifiesforexam

One can simply add a new .rst file, and reference it below one the sections, or create a new section.