Documentation Design

As befitting a project of SymEngine’s scope, a discussion of the documentation design is appropriate. The overall design is spread across multiple repositories, but unified under a single domain.

Note

Not covered in this design document are the manual benchmarking requirements, and the project todo strategy

Goals

The documentation goals are:

  • Link to the API documentation when appropriate

  • Allow each language binding to build and control the API documentation builds

  • Supplement the existing channels of communication

In particular, the third point means that there is to be a clear separation of content between the User Wiki, the API documentation, and the main site.

Decisions

These decisions codify the guiding principles of the documentation.

No Versioning

Search engines are typically thrown by versions, e.g. CMake and its documentation setup; and since backward compatibility is not necessarily guaranteed, there is no point hosting multiple versions.

However, only the latest stable set of bindings are to be described here; that is; those published with the official distribution system, conda.

Review Tutorials

The contents of the tutorials (the ones linked from the organization site) are built with sphinx-dust to ensure that they are checked routinely; every \(60\) days by default.

Doc Warnings are Errors

The documentation is built weekly, as discussed in the next section; and all warnings are treated as errors.

Implementation

CI and Hosting

All builds are through isolated Github Actions jobs and hosted with Github Pages. The documentation is rebuilt weekly on a cron job, and also tested for each pull request and push for the API and the main site.

API Bindings

Given the separation of concerns; each language binding is built in the most native fashion; currently this means the tools

Language

Tool

C++

Doxygen

R

pkgdown

Python

Sphinx

Julia

Documenter.jl

Additionally, to ensure cross-linking of references; the C++ outputs are additionally parsed with parsed with sphinx using doxyrest.

Main Site

The main site is meant to serve as an entry point to new users.

Build System

The site is to be built in production with the rake tasks provided; though for local development other methods and helpers are provided.

Note

Several common errors can be caught with the prePub task

Content and Syntax

The content is to be written in Markedly Structured Text or myST, which is a super-set of CommonMark markdown and has additional extensions for Jupyter Notebooks (with myST-NB and jupytext) and reStructured Text.

Files which are meant to be executed; that is those which are tangled with jupytext must have the .myst.md extension.

Warning

Failure to specify the extension in the YAML headers in each .myst.md file will cause unexpected behavior

Interactivity

Every tutorial must be accompanied by the following:

Binder Button Binder

The launch in binder is to populated manually and placed on the first heading of the file and should point to the appropriate myst.md file which is on the sources branch

Warning

The .binder/environment.yml must be kept in sync with the symedocs.yml file

Colab Button Colab

The launch button, like the binder button above should point to the appropriate file, which in this case is the .ipynb file on the notebooks branch

Local Button Local Installation

This button is required, and should direct the user to the tutorial follow along instructions

Furthermore, the tutorials are to be proofread every \(60\) days, otherwise the cron builds will start to fail.

Docs are Tests

Each .myst.md is to be executed on the repository CI system when the API documentation is built. This is facilitated by papermill.

Acknowledgments

Apart from the tireless efforts of the core development team and volunteers; part of the documentation process was supported over the course of the 2020 Season of Docs.

Review

Written on 14 February 2021, proofread on 16 February 2021