Documentation

Software

Software we use

Our software are documented with the following.

rustdoc

A simple cargo doc generates the code documentation for a rust crate.

Spectacle

Spectale generates documentation from OpenAPI / Swagger specification. It gives something like this.

Sphinx

Generate book-like documentation, manuals, guides from reStructuredText. It's used by some Python software.

Software to explore

The following software seems interesting to solve documentation needs.

BookJS

BookJS is a JS lib that can turn a webpage into a formatted Book ready to print to PDF. It is Alpha and available under the AGPL. Developed by the Booktype team for inclusion in any project. There is also a BookJS rendering engine (webkit+BookJS) to create the PDF. - http://bookjs.net/

Wikihtml2man.1

Wikihtml2man is an easy to use converter that parses HTML sources, normally originating from a Mediawiki page, and generates Unix Manual Page sources based on it (also referred to as html2man or wiki2man converter). It allows developing project documentation online, e.g. by collaborating in a wiki. It is released as free software under the GNU GPLv3. Technical details are given in its manual page: Wikihtml2man.1.

Mermaid

Workflow, gantt and sequence diagrams from Markdown - https://mermaidjs.github.io/

Documentation hosting

Nasqueron hosts documentation at https://docs.nasqueron.org

Provide a new content

Instructions for new content should be added to this file: rOPS: operations/roles/webserver-content/org/nasqueron/docs.sls.

Static documentation

Add the software or documentation repository to the staging repository, and deploy it with a file.recurse.

Dynamic documentation

Create a Jenkins job (with a Jenkinsfile pipeline as code committed to the repository) in the CD instance. A build plan and an Herald rule in Phabricator can run the job each commit. Finally, a Salt state to run the job is needed too for provisioning (don't put requirements, this state is intended to be run each time we need to refresh all doc).

Add new doc to the the homepage

This file needs to be modified: https://devcentral.nasqueron.org/source/docs-www/browse/master/src/data/docs.yml