Documentation: Difference between revisions
From Nasqueron Agora
(Created page with "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 ...") |
|||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
== Software == | |||
=== Software we use === | |||
Our software are documented with the following. | |||
;rustdoc | |||
:A simple <code>cargo doc</code> generates the code documentation for a rust crate. | |||
;Spectacle | |||
:Spectale generates documentation from OpenAPI / Swagger specification. It gives something like [https://docs.nasqueron.org/docker-registry-api/ 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. | The following software seems interesting to solve documentation needs. | ||
| Line 6: | Line 21: | ||
;Wikihtml2man.1 | ;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. | :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: {{Ops file|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 <code>Jenkinsfile</code> 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 | |||
[[Category:Knowledge base]] | [[Category:Knowledge base]] | ||
Latest revision as of 21:36, 27 November 2018
Software
Software we use
Our software are documented with the following.
- rustdoc
- A simple
cargo docgenerates 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
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
