Using the technical documentation generator

Introduction

The purpose of this section is to provide ‘quick’ reference information (on syntax, available tools, style conventions, etc) that may be required by technical writers or translators working with the project documentation.

The most important information is about reStructuredText, the markup language used in the technical documentation (user manual, etc.).

There is also some (basic) information about Sphinx, the application that automatically converts the text files and generates the documentation in HTML format or PDF format.

For example, this HTML page was originally written in reStructuredText. Please, press the Source link in the menu to see the original text and markup.

References

• About Sphinx
• Sphinx’s reStructuredText primer
  • Introduction
  • Paragraphs
  • Sections
  • Inline markup
  • Lists
  • Tables
  • Hyperlinks
  • Source Code
  • Explicit Markup
• Tools for reStructuredText
  • Introduction
  • Editors
  • Builders and converters
  • Integrated solutions
• Publishing the documents online
  • Introduction
  • Dropbox
  • Google drive
  • Read The Docs
  • Github.io
• Showing source code examples in Sphinx
  • Highlight directive
  • Code-block directive
  • Literalinclude directive
  • Pygments lexers
• Creating diagrams in Sphinx
  • Using Graphviz
  • Using PlantUML
  • Class diagram
  • Use case diagram
  • Activity diagram (new syntax)
  • State diagram
  • GUI mockups
• Managing bibliographic citations in Sphinx
  • Introduction
  • Using Sphinx BibTeX extension
  • Using LaTeX directly in Sphinx
  • Managing BibTeX bibliographies
• Creating equations in Sphinx
  • LaTeX
  • MathJax
  • Equation editors or previewers
  • Examples