Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
PROJECT DOCUMENTATION
WITH SPHINX
(or, How I Learned to Stop Worrying
and Love reStructuredText)
Dan Gillean
Artefactual S...
BACKGROUND
20142008
0.X-BETA 1.0-BETA
FIRST
NON-BETA
RELEASE
AtoM DEVELOPMENT
1.1 2.01.31.2
TRILLIUM THEME
2013:
1 PROJECT…
3 WIKIS
4 THEMES
And AtoM 2.0 on the way…
http://imgur.com/32eaxCQ
WIKICHALLENGES
No versioning (e.g. ICA-AtoM 1.2, 1.3; AtoM 2.0)
No enforced structure
Too easy to create orphaned pages
No...
ENTER
http://onemillionskates.com/inside-edge/a-true-hero-dad-this-ones-for-you
OVERVIEW
Documentation generator
Open source
Created by Python community
Builds on existing open source projects:
- reStru...
OVERVIEW
reST BASICS
http://blog.sleepingsimple.com/wp-content/uploads/2012/03/Cat-Nap.jpg
reST BASICS
.. _section-anchor:
==============
Section header
==============
Subsection header
=================
Sub-subse...
reST BASICS
.. IMPORTANT::
This is an admonition. Sphinx
also supports NOTE, TIP,
SEEALSO, WARNING, CAUTION,
HINT, etc.
Th...
ADVANTAGES
• Structured documentation
• Built around a table of contents you define
• Versioning
• Easily maintained in a ...
WIKISSTILLHAVETHEIRUSES!
• Web-based editing
• Popular uses (e.g. Wikipedia) have
made it familiar and easy to
understand ...
THANKS!
AtoM docs: https://www.accesstomemory.org/docs
Documentation repo: https://github.com/artefactual/atom-docs
Sphinx...
Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText)
Upcoming SlideShare
Loading in …5
×

of

Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 1 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 2 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 3 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 4 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 5 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 6 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 7 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 8 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 9 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 10 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 11 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 12 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 13 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 14 Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText) Slide 15
Upcoming SlideShare
ReST Editor - Eclipse Demo Camp Grenoble 2011
Next
Download to read offline and view in fullscreen.

2 Likes

Share

Download to read offline

Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText)

Download to read offline

Slides accompanying a lightning talk delivered at BC Code4Lib 2015, held in Vancouver, BC, Canada on November 26-27, 2015.

This talk covered our move from using wikis for project documentation with the Access to Memory (AtoM) project, to using Sphinx documentation with the AtoM 2.0.0 release.

More on AtoM: https://www.accesstomemory.org
More on Sphinx Documentation: http://sphinx-doc.org/
Code4Lib BC: http://wiki.code4lib.org/BC

Related Books

Free with a 30 day trial from Scribd

See all

Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Love reStructuredText)

  1. 1. PROJECT DOCUMENTATION WITH SPHINX (or, How I Learned to Stop Worrying and Love reStructuredText) Dan Gillean Artefactual Systems
  2. 2. BACKGROUND
  3. 3. 20142008 0.X-BETA 1.0-BETA FIRST NON-BETA RELEASE AtoM DEVELOPMENT 1.1 2.01.31.2 TRILLIUM THEME
  4. 4. 2013: 1 PROJECT… 3 WIKIS 4 THEMES And AtoM 2.0 on the way… http://imgur.com/32eaxCQ
  5. 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
  6. 6. ENTER http://onemillionskates.com/inside-edge/a-true-hero-dad-this-ones-for-you
  7. 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. 8. OVERVIEW
  9. 9. reST BASICS http://blog.sleepingsimple.com/wp-content/uploads/2012/03/Cat-Nap.jpg
  10. 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. 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.
  12. 12. 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
  13. 13. 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
  14. 14. THANKS! AtoM docs: https://www.accesstomemory.org/docs Documentation repo: https://github.com/artefactual/atom-docs Sphinx documentation: http://sphinx-doc.org/
  • ChristyJenkins4

    Nov. 23, 2021
  • MarcusBarnes

    Dec. 2, 2015

Slides accompanying a lightning talk delivered at BC Code4Lib 2015, held in Vancouver, BC, Canada on November 26-27, 2015. This talk covered our move from using wikis for project documentation with the Access to Memory (AtoM) project, to using Sphinx documentation with the AtoM 2.0.0 release. More on AtoM: https://www.accesstomemory.org More on Sphinx Documentation: http://sphinx-doc.org/ Code4Lib BC: http://wiki.code4lib.org/BC

Views

Total views

1,580

On Slideshare

0

From embeds

0

Number of embeds

9

Actions

Downloads

20

Shares

0

Comments

0

Likes

2

×