Software we use
Our software are documented with the following.
- A simple
cargo docgenerates the code documentation for a rust crate.
- Spectale generates documentation from OpenAPI / Swagger specification. It gives something like this.
- 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 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 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.
- Workflow, gantt and sequence diagrams from Markdown - https://mermaidjs.github.io/
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
Jenkinsfilepipeline 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