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.
Not covered in this design document are the manual benchmarking requirements, and the project todo strategy
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.
These decisions codify the guiding principles of the documentation.
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,
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.
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.
Given the separation of concerns; each language binding is built in the most native fashion; currently this means the tools
The main site is meant to serve as an entry point to new users.
The site is to be built in production with the
rake tasks provided; though for local development other methods and helpers are provided.
Several common errors can be caught with the
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
Failure to specify the extension in the YAML headers in each
.myst.md file will cause unexpected behavior
Every tutorial must be accompanied by the following:
- Binder Button
The launch in binder is to populated manually and placed on the first heading of the file and should point to the appropriate
myst.mdfile which is on the
.binder/environment.yml must be kept in sync with the
- Colab Button
The launch button, like the binder button above should point to the appropriate file, which in this case is the
.ipynbfile on the
- Local Button
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.
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.
Written on 14 February 2021, proofread on 16 February 2021