3. Sphinx Documentation

Read The Docs Grader Service Documentation provides users of the Grader Service application with all the relevant details for installing Grader Service, interacting with the user interface (both in instructor and student modes), and offers an interactive view of the Grader Service OpenAPI specification.

For generating our documentation we are using Sphinx python Documentation Generator. To work and contribute to documentation of Grader Service navigate to docs/ directory.

Requirements

To create documentation using Sphinx, you must first install it along with the following packages:

sphinx
pydata-sphinx-theme
myst-parser
numpydoc

You can also install all the necessary requirements by executing:

pip install -r docs-requirements.txt

Understending Sphinx Package

You can add new files or work on existing documentation pages in the docs/source directory. All of the files are in the reStructuredText (.rst) format. To become familiar with reStructuredText, please take a look at its documentation.

In the _static/ directory, you will find all static attributes of the documentation, including used pictures, custom CSS, and OpenAPI Schemas.

In the source directory, there is an essential file named conf.py. It controls how Sphinx processes your documents and is executed as a Python source file. For more in-depth information about the configuration, you can read it here.

Relevant parts of configuration

• Extensions: Since many projects will need special features in their documentation, Sphinx allows adding “extensions” to the build process, each of which can modify almost any aspect of document processing. Currentlly used extensions are:

extensions = ["sphinx.ext.autodoc",
          "sphinx.ext.autosummary",
          "sphinx.ext.doctest",
          "sphinx.ext.extlinks",
          "sphinx.ext.viewcode",
          "sphinx.ext.todo",
          "numpydoc",
          "sphinx.ext.intersphinx",
          "sphinx.ext.coverage",
          "sphinx.ext.mathjax",
          "sphinx.ext.ifconfig",]

• html_theme: Specifies which theme to use for HTML pages. Currently used theme is pydata_sphinx_theme. If you want to change this theme to another 'no builtin' theme, it must be first installed. Make sure to also add the new theme to doc-requirements.txt! Example of installing and setting a new theme:

# installing theme package
# if you really want to change the theme, remeber to specify it in doc-reguirements.txt file in `docs/` directory!
pip install sphinxjp.themes.dotted

Once installed, set new theme in conf.py:

html_theme='dotted'

• html_static_path: Specifies the path to the static files for your documentation and is relevant to root directory docs.

html_static_path = ['_static']

• html_sidebar: Custom sidebar templates, must be a dictionary that maps document names to template names.

html_sidebars = {
"**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"]
}

Generating documentation

In directory docs/, execute:

make html

This instruction will generate a build directory, in which you'll find html and doctrees directories. To have a live preview of how your documents will look once they are published, run the following command:

(cd build/html/ && python3 -m http.server)

You can now view your documentation at http://localhost:8000. If you make any changes, in order for them to be visible when you start a server, you must execute make file. That's why you should serve HTML files in another terminal. After executing make file, refresh the localhost webpage, and your changes should be visible.

Update API Documentation

Directory docs/grader_service contains a file named grader_service_rest_api.rst which will render an interactive overview of the Grader Service OpenAPI specifications.

This file contains a sript, which renders the interactive API view based on grader_api.yml from _static/openapi/ directory:

const ui = SwaggerUIBundle({
  url: '../_static/openapi/grader_api.yml',
  dom_id: '#openapi-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIBundle.SwaggerUIStandalonePreset
  ],
  layout: "BaseLayout",
  deepLinking: true,
  showExtensions: true,
  showCommonExtensions: true,
});

API models can be added or updated in _openapi/schemas.yml. If you updated schemas.yml, Rest API documentation will be updated automatically. If you don't see your changes when serving documentation HTML files, make sure to delete cookies. It also could take some time for API interactive view to be generated.

Publishing documentation

For hosting our documentation online, we use Read the Docs , an open-sourced free software documentation hosting platform. It generates documentation written with the Sphinx documentation generator. To publish new version of documentation, please visit https://readthedocs.org/projects/grader-service/. You must be added as a maintainer to build a new version. Ensure that all relevant documentation changes are merged into the main branch of the Grader Service GitHub repository to make them visible in the newly published version. No further steps are required, you just have to click on build button and wait until new version is done building. No further steps are required; simply click the build button and wait until the new version finishes building. Your changes should be visible immediately at this link.