Open discussions on specific topics selected by the Software Working Group and selected from the list of SWG Topics For Discussion.
Sphinx, docstrings and autodoc
Moderated by Mikolaj Kowalik
Good code does not need documentation. Wrong! A good documentation is an essential part of any code base. Why? Because people shouldn’t need to read all of your code in order to understand what it does. However, writing a good documentation takes that extra time and effort. Luckily, there is Sphinx which makes the task of creating beautiful documentation less daunting. So let's take a closer look at Sphinx & its friends.
Recording: https://uofi.box.com/s/twngtbb994rog49fuhppv8rgc9jr0f1t
Slides: https://docs.google.com/presentation/d/1DqJDoqRuVgZnzGPy8L9yDdDfXdGvG2puImqKQsrXDLA/edit#slide=id.p
Attendees:
Mikolaj Kowalilk
Luigi Marini
Rob Kooper
Rebecca Eveland
Jong Lee
Sara Lambert
Chen Wang
Chris Navarro
Craig Steffen
Matt Berry
Max Burnette
Roland Haas
Andrew Manning
Jeff Terstreip
Dipannita Dey
Bing Zhang
Lisa Yanello
Kastan Day
Rashmil Panchani
Jong Lee
Minu Mathew Rob note
Discussion:
Why is documentation so important? Do you want others to use your code? Will you be using your code in 6 months? Do you want your code to be better? Max notes that he sometimes starts with documentation, which helps organize his thoughts, then write the code.
Docs as code: Plain text files, version control (GIT), Automated validation, Continuous publishing, Issue trackers, code reviews.
Types of Documentation: Tutorials, User Guides, Reference Guides
What is Docstring? A docstring In programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code.
Sphinx has a steep learning curve for non programmers; documents are written in reStructuredText markup language. Andrew suggests using Markdown for documentation over reStructuredText that does not have as much support. Craig Steffen notes that Sphinx could not get Sphinx to use Markdown.
reStructuredText is pretty standard, whereas Markdown comes in many different formats.
Sphinx Pros:
- Writers like single source publishing, multimple mature HTML themes
- Referencing across pages, index and glossary support, internationalization support
- Developers like semantic referencing of software concepts, code comments in documentations.
The Ecosystem has built-in extensions (autodoc, autosummary, doctest and more. They also have contributed extensions sphix-argparse, sphinx-autoapi, sphinx-automodapi, breathe and pyPi
Final words: Document or it didn't happen - Jonathan Sick
Rob Kooper notes that rst (reStructuredText) and Markdown are very different. Are there easy ways to lint it in rst (the dots in front of the text mean something) Craig confers. Rob states that Latex is his preferred documentation tool
If you are interested in contributing to a Round Table, please see these links:
Round Table Google Sheet: https://docs.google.com/spreadsheets/d/1kbgO6sIb_4eLugfSVKQNCTXdaKp1R6m0RDczPTsUAoQ/edit#gid=0 Every one should have edit permission.