Document your code (Sphinx workshop)

Kushal Das (~kushal)


12

Votes

Description:

To learn how to write documentation for your code-bases. Documentation is the key for communication and developers are the best person to start writing it. Projects can succeed or fail because of their documentation.

In the workshop the people will be introduced to reStructuredText & sphinx. Starting from quick-start of a project to document organization, code and topic cross-referencing, indexing. We will also go through running tests from your documentation, initial ideas on themes and deployment in readthedocs.

Quick summary of the workshop

  • Introduction to reStructuredText
  • Introduction to sphinx
  • Difference with other systems
  • A project structure with docs
  • hands-on tutorial with sphinx
    • Creating a new documentation for a project
    • Detailed documentation steps using sphinx
    • Generating various formats of output
    • Special cases in sphinx
    • Usecase of Python itself
  • Integration with readthedocs

Prerequisites:

Participants should have the following package installed on their computers

  • python-sphinx

Content URLs:

  • http://www.dgplug.org/irclogs/2012/rst-primer/
  • https://kushaldas.in/talks/documentyourcode/#/step-1 (The slides from the related talk)

I have done this workshop previously 2 times in PyCon India (2013-2014), and also in other conferences. Gave it a gap of 1 year, and putting it in this year.

Speaker Info:

Kushal Das is a CPython core developer and director at the Python Software foundation. He has been a mentor and an Ambassador at The Fedora Project. Along side his contributions to CPython, Kushal has also been contributing to a wide variety of upstream projects. He started Linux Users Group of Durgapur and wrote a book titled "Python for you and me". He is currently working as Fedora Cloud Engineer at Red Hat.

Speaker Links:

  • https://kushaldas.in

Section: Others
Type: Workshops
Target Audience: Beginner
Last Updated: