You have python code, how to document your API with Sphinx?

Simple four steps to get the HTML files from your python code

You just need four steps.

• Execute sphinx_quickstart, and make sure that you check autodoc mode on:> autodoc: automatically insert docstrings from modules (y/N) [n]: y
• In conf.py, add the path to your source code: sys.insert('./../src')
• Execute sphinx-apidoc -o . ../src/
• Execute make html

Now, you will have your python code in HTML format.

Include reST documents into index

Topic and comments

topic directive creates

tag in HTML. It seems to be pretty useful in describing what the reST document does.

.. topic:: What is Sphinx and the RST syntax ?
 
   CONTENTS ...

When you just use two dots, it works as a comment.

toctree

When you open the index.html, you will see nothing in the contents. It is because there is nothing under the toctree directive. Open the index.rst file which is the main reST for your project. You need to add the modules.

.. toctree::
   :maxdepth: 2
   
   hello1

You may not want to show toctree. This will notify Sphinx of the document hierarchy, but skip inserting links into the document.

.. toctree::
   :hidden:

You can make toctree numbered with :numbered: field.

.. toctree::
    :maxdepth: 1
    :numbered:

:doc:`…`

In this case, you can explicitly include the reST document with :doc:`…` field.

:doc:`hello1`
  Instructions on how to get the distribution.

API documentation

In step3, we can get (semi) automatically generated API documentation file from Sphinx with sphinx-apidoc command. Whenever you want to add more documentation to it, you have to do it manually.

Including math in the documentation

Add 'sphinx.ext.pngmath' in the extensions list. Then, use math directive or field:

:math:`a^2 + b^2 = c^2`.

.. math::

(a + b)^2 = a^2 + 2ab + b^2
(a - b)^2 = a^2 - 2ab + b^2

You need to specify the latex location in your computer. sphinx-build -b html -D pngmath_latex=`which latex` . _build/html.

Useful Sphinx knowledge

Extensions

In conf.py, you can add more Sphinx features with extensions list.

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.viewcode','sphinx.ext.todo']

References

• sphinx.ext.autodoc – Include documentation from docstrings
• TOC tree in Sphinx
• Documenting your project Using Sphinx
• sample doc tutorial

Type checking in Python

Python's value has a type, however a variable can be assigned to any typed value.

>>> a = A()
>>> a is A
False
>>> id(a)
3567120
>>> id(A)
2377856

>>> id(type(a))
2377856

>>> type(a) is A
True

>>> a.__class__ is A
True

>>> isinstance(a, A)
True

Equalities

It seems to be simple to compare two values: 1 == 1 or 2 == 3? However, when a variable is assigned to a value, it's a little bit more complicated: x = 3, y = 3, x == y? The different type of data can represent the same value: 1.0 == 0?

Lisp

> (= 1.0 1)
T

> (eql 1.0 1)
NIL

> (eql (cons 'a nil) (cons 'a nil)
NIL

> (setf x (cons 'a nil))
> (eql x x)
T

> (equal x (cons 'a nil))
T

C/C++

int x = 10;
int y = 20;

x == y // equal in Lisp
&x == &y // eql in Lisp
10 == 20 // = in Lisp

Python

>>> x = 10
>>> id(x)
1764365084

>>> y = 10
>>> id(y)
1764365084

>>> x is y // eql in LISP
True

>>> x == y // equal in LISP
True

>>> a = [1,2,3]
>>> a == [1,2,3]
True

>>> a is [1,2,3]
False

>>> id(a)
4359792
>>> id([1,2,3])
4225424

Reference

• Python “is” operator behaves unexpectedly with integers
• What is the semantics of 'is' operator in Python?

Merge two lists in Python

When you merge two lists with Python, you can use the overloaded '+' operator.

a = [1,2,3]
b = [2,3,4]

>>> a + b
[1, 2, 3, 2, 3, 4]

However, when you don't want the duplicate values, you need to use set. '+' operator is not supported in a set, so use union() method.

>>> set(a).union(b)
set([1, 2, 3, 4])

You can convert a set to list with list() method.

>>> list(set(a).union(b))
[1, 2, 3, 4]

Refer to set in python document.

endianness

When programming on Intel CPU, I wondered why the debugger showed the integer values reverse order. The AX register has the value 0x04030201, but when I store the value in memory at 0x1000, the value I see at 0x1000 is 01020304.

That's because Intel uses little endian for their CPU architecture. Little endian stores LSB byte (little byte) first whereas big endian stores MSB first. So the stored value will be 04030201. It's also because we write numbers from left to right. If we have the culture to write from right to left, the little endianness looks OK as we would write 010203040x.

The Internet Protocol defines big-endian as the standard network byte order. When streaming multiple byte data, the first arrived byte is the MSB.

Reference

• wikipedia
• endian-ness of bits and bytes

Deleting elements in map: C++ and Python

C++

std::listlist<int> keys;
// 1. get all the keys that has the elements from bList
for (std::listlist<int>::iterator it = bList.begin(); it != bList.end(); ++it)
{
    for (std::map<string, int>::iterator j = aMap.begin(); j != aMap.end(); ++j)
    {
        if (j->second == *it) keys.push_back(j->first);
    }
}

// 2. remove all the items of the key
for (auto it = keys.begin(); it != keys.end(); ++it)
{
    aMap.erase(*it);
}

std::list<int> keys;
for (auto it = bList.begin(); it != bList.end(); ++it)
{
    for (auto j = aMap.begin(); j != aMap.end(); ++j)
    {
        if (j->second == *it) keys.push_back(j->first);
    }
}

// 3. remove all the items of the key
for (auto it = keys.begin(); it != keys.end(); ++it)
{
    aMap.erase(*it);
}

Python

http://stackoverflow.com/questions/11277432/how-to-remove-a-key-from-dictionary

for e in elements:
    if e in aDict:
        del aDict[e]

for e in elements:
	aDict.pop(e, None)

Alloy example1 - Linked list

Using Alloy, we can make an abstraction model of linked list. Linked list should have the following properties.

• It should have one header as a starting Node, it can link to another Node or null.
• Node has a link which can be another Node or null.
• There should be no cycle.

sig List and Node

The first an second property can be described with “sig”.

one sig List { header: lone Node }

The form of Alloy code looks like a class in OOP, but it’s actually a set. Alloy visually models the member as a label in the arrow, and List as a box.

List has a member named header which can be one of less than one (lone) Node member.

You can think header as a variable name, and Node as the type of the variable.

sig Node { link: lone Node }

Predicate

Then you can have a predicate that is true or false. You can use predicate for describing the acyclic property.

predicate looks like a method or function as it has parameters.

You can describe many ways to describe acyclic, one of them can be “all nodes should not be a link as null”.

And don’t forget about the header, so the link should start from header : link.header.*link

pred acyclic (l : List)

{

        all n : l.header.*link | n !in n.^link

}

l.header.*link means l.header, l.header.link …

n.^link means n.link …

We check the predicate with “run acyclic” as if predicate is an entity to execute.

Alloy returns a list and two nodes that doesn’t have a cycle from the header, but it’s not what we expect.

We missed the fact that all the links from the header should be a Node (that is, has a link of Node or null)

fact

{

        List.header.*link = Node

}

Now, we finally have what we expect.

Equivalence

You can describe the acyclic property in many forms, and you can prove the equivalence between them using Alloy.

pred acyclic2 (l : List)

{

        no l.header or

        some n: l.header.*link | no n.link // n.link is null

}

This predicate says that there can be a link without any element (base case), and some link from List.header.*link should have null. (induction case). Lone means zero or one, no means zero.

pred acyclic3 (l: List)

{

        no (l.header).~link and

        (all n: l.header.*link | lone n.~link)

}

~link means that something that refers link. It means that header’s link is not referenced, and all the links are referenced at most once.

You can run predicates, or you can assert the equivalence.

assert Equiv

{

        all l : List | acyclic[l] <=> acyclic2[l]

}

check Equiv for 5

This command says check the assert with at most 5 elements.

Alloy transforms the code into SAT format, and runs the SAT solver to find a counter example, but it can’t find solution to this SAT problem, so it says they are equivalent.