Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText)
Download as PPTX, PDF2 likes1,821 views
The document discusses project documentation using Sphinx, highlighting its evolution and advantages such as structured organization, versioning, and ease of maintenance. It mentions the foundational technologies like reStructuredText and Docutils, along with various features supported by Sphinx for document generation. Sphinx is positioned as an effective solution for generating documentation, particularly for software projects, with links provided for further resources and examples.
Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText)
- 1. PROJECT DOCUMENTATION WITH SPHINX (or, How I Learned to Stop Worrying and Love reStructuredText) Dan Gillean Artefactual Systems
- 2. BACKGROUND
- 3. 20142008 0.X-BETA 1.0-BETA FIRST NON-BETA RELEASE AtoM DEVELOPMENT 1.1 2.01.31.2 TRILLIUM THEME
- 4. 2013: 1 PROJECT… 3 WIKIS 4 THEMES And AtoM 2.0 on the way… http://imgur.com/32eaxCQ
- 5. WIKICHALLENGES No versioning (e.g. ICA-AtoM 1.2, 1.3; AtoM 2.0) No enforced structure Too easy to create orphaned pages No easy output to other formats https://commons.wikimedia.org/wiki/File:Coober_Pedy_Warning_sign_02427.jpg
- 7. OVERVIEW Documentation generator Open source Created by Python community Builds on existing open source projects: - reStructured Text (markup language) - Docutils (text processing system)
- 8. OVERVIEW
- 10. reST BASICS .. _section-anchor: ============== Section header ============== Subsection header ================= Sub-subsection -------------- Example of a :term:`glossary term` and a :ref:`section-anchor <reference>` used in a paragraph .. image:: /images/my-image.png :align: center :width: 80% :alt: my image alt text Text can be **strong** or have *emphasis*
- 11. reST BASICS .. IMPORTANT:: This is an admonition. Sphinx also supports NOTE, TIP, SEEALSO, WARNING, CAUTION, HINT, etc. This is a `link`_ that can be reused .. _link: http://www.example.com This is an `inline link <http://www.example2.com>`__ .. code-block:: xml <scopecontent>My scope and content</scopecontent> * This is a bulleted list. * It has two items, the second item uses two lines. 1. This is a numbered list. 2. It has two items too. #. This is a numbered list. #. It has two items too.
- 13. ADVANTAGES • Structured documentation • Built around a table of contents you define • Versioning • Easily maintained in a repository w many branches • Easy output to other formats • Glossary, footnotes, asides, figures, tables, etc… • Built-in themes or custom themes • Automated indices • Strong support for code documentation http://cheezburger.com/6705529088
- 14. WIKISSTILLHAVETHEIRUSES! • Web-based editing • Popular uses (e.g. Wikipedia) have made it familiar and easy to understand for users • Good for rapidly changing content AtoM Sphinx docs: • User manual • Admin manual AtoM Wiki: • Release notes • User list • Community resources • Development documentation
- 15. THANKS! AtoM docs: https://www.accesstomemory.org/docs Documentation repo: https://github.com/artefactual/atom-docs Sphinx documentation: http://sphinx-doc.org/
Editor's Notes
- #9: Many other formats built-in: Windows/Apple/GNOME Help books, man pages, txt files, JSON, etc. Further builders available as third-party open-source extensions