Flock/Volunteers/DocumentYourCode

These notes were taken by Dave Crossland. http://understandingfonts.com/blog/2013/08/flocktofedora-day1/

Document Your Code, by Kushal Das

The Big Idea is: Documentation is Communication.

Documenting source code is critical to on boarding new developers to a project.

reStructuredText is the Pythonic markdown-style mark-up.

You need Fedora packages python-docutils and python-sphinx

“

Document Title Text

SOmething in a paragraph. “

$ rst2html.py example.rst example.html $ open example.html

:)

There is syntax for titles and headings, ul and ol lists, with auto enumeration with

1. Point

. Else

dl lists, command line option lists.

Literal blocks are done with ::

Look up the full syntax online :)

Q: converters to rst?

A: Yes, mediaWiki has a extension, and markdown2rst and rst2markdown exists.

…

pycon-us-2013.txt is a good read, and this guy made a rst blogging tool, ‘Nicola’ – https://github.com/ralsina/nikola -

pocoo made http://sphinx-doc.org/

So lets see an example Python source code file, here is a simple class file with a class Rectangle(object) :)

“ ”’ This is a module of Rectangle class. ”’

class Rectangle(object):

def init(self, length, width): self.length = length self.width = width

def area(self): ”’ Returns the area of the rectangle. ”’ return self.length * self.width

def is_square(self): ”’ Finds out if it is a square or not. ”’ return self.length == self.width

“

This is at http://kushal.fedorapeople.org/rectangle.py

lets turn it into a full module

$ mkdir shapes; $ cd shapes; $ touch init.py; $ cp rectangle.py shapes/; $ mkdir doc/; $ touch doc/index.rst;

The index.rst is the project documentation.

“

The project

Intro to the project.

“

Now lets use Sphinx to add documentation:

“ ”’ This is a module of Rectangle class. ”’

class Rectangle(object):

def init(self, length, width): ”’ Returns an object of Rectangle class.

:arg length: Length of the rectangle

arg width: Width of the rectangle

:return: rectangle object with given length and width.

.. notes::

This is a note

”’ self.length = length self.width = width

def area(self): ”’ Returns the area of the rectangle. ”’ return self.length * self.width

def is_square(self): ”’ Finds out if it is a square or not. ”’ return self.length == self.width

“

$ make html $ open build/docs/index.html

$ touch doc/quickstart.rst; “ This is a quick start doc ————————– This is the paragraph with a direct link to the project’s class like this :class:~shapes.rectangle.Rectangleclass. or also a method like :meth:~shapes.rectangle.Rectangle.area. “

$ make html $ open build/docs/index.html

We can now see this on the build/docs/index.html page

So you should have 3 pieces of essential documentation for any project:

1. A quick start page to get the most common usage going
2. A tutorial that is more in depth
3. API documentation

Lets make the 3rd now :)

$ touch doc/api.rst; “ API for our Shapes module ————————–

.. autoclass:: shapes.rectangle.Rectangle

members:

“ $ make html $ open build/docs/index.html

We can also

$ make pdf

This creates LaTeX from the RST and then a PDF from that.

…

https://github.com/kushaldas/retask is an example of a real Python package I made that I used Sphinx to document at http://retask.readthedocs.org/en/latest/