It doesn’t matter if you are creating project for your company or you plan to release it as an open source – by providing documentation you make life easier for other contributors and end-users, of course. And if you know how to write restructuredText documents then you already own necessary skills to create documentation lighting fast!

Prepare!

First of all, you would need to have Distutils and Sphinx installed. You can install it using one of the Python package management tools, in example easy_install would do the job. I prefer to use pip:

pip install distutils
pip install sphinx

Simply use any project you’d like to create documentation for, I would use django-richtemplates. Create a new directory for your documentation and run sphinx-quickstart command:

hg clone https://bitbucket.org/lukaszb/django-richtemplates/ django-richtemplates-temp
cd django-richtemplates-temp
sphinx-quickstart

Just answer some questions – they are very straightforward. You should probably turn autodoc option on.
Sphinx would create some directories for internal usage and static content storage (_build, _static and _templates), configuration file (conf.py) and index file (index.html). Ok, enough of this crap, lets create our first documentation page!

First page

Create new file, lets call it installation.rst and write the document itself:

.. _installation:

============
Installation
============

Fake installation for `django-richtemplates`_ project.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.

.. note::
   Yeah, this would be a note.
   Very simple, indeed.

Some more crap
--------------

If you would like to highlight a code snippet, it is as easy as::

   from mycompany.auth import AuthenticationBackend

   class MyClass(object):
       """
       Docstring.
       """
       def __init__(self, *args, **kwargs):
           """
           Some *business* logic.
           """
           pass
       def authenticate(self, username, password):
           """
           External authentication process.
           """
           auth = AuthenticationBackend(username, password)
           return auth.is_authenticated()

Or choose language explicit:

.. code-block:: bash

   cd django-richtemplates
   sudo python setup.py install

Yeah, `restructuredText `_ is great!
And easy, too.

External-internal hyperlinks
----------------------------

You may also use ``sphinx`` features, like linking to other *documents*, like
this: go to :ref:`configuration`.

.. _django-richtemplates: http://bitbucket.org/lukaszb/django-richtemplates/

This is standard restructured text document. The only sphinx specific parts are first line (need to add relation with file itself – this is needed for table of contents generation) and reference to other file (which is done with ref:`configuration`). Yup, we haven’t created configuration.rst file, yet. So do this now, and paste following:

.. _configuration:

=========================
Configuring richtemplates
=========================

I hope you have already read chapter :ref:`installation`.

Lorem ipsum!
------------

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.

Don’t forget about the main page!

I once hoped that the first page (namely index.rst) is generated automatically, yet, I was wrong. But in order
to supply needed data for sphinx generator you have to make very simple changes to the index.rst. Just add
:glob: option to the toctree directive. Finally, mark that all (*) restructuredText documents should
be used.

.. django-richtemplates documentation master file, created by
   sphinx-quickstart on Sat Feb 20 21:42:53 2010.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to django-richtemplates's documentation!
================================================

Contents:

.. toctree::
   :maxdepth: 2
   :glob:

   *

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Now in mydocs directory run

make html

and open file located at mydocs/_build/html/index.html. You should see your documentation!

Final words

Ok, this was very simple and the effect is – for such a little work done – quite amazing if you’d ask me.
However, we still haven’t used autodoc Sphinx’s extension. Let’s do that now – create new file
api.rst and paste whats below:

.. _api:

===
API
===

You can find some basic API information here.

Forms API
---------

In this section we cover some basics about the `django-richtemplates`'s forms
API.

.. automodule:: richtemplates.forms
   :members:

.. _django-richtemplates: http://bitbucket.org/lukaszb/django-richtemplates/

Again, run make command and see your documentation. Ok, so where is your API, you ask? Well, if you look at the output
of make html command you’d see that there was a warning – richtemplates.forms couldn’t be found.
Which is completely correct, as Sphinx doesn’t try to guess where your modules are, you have to configure it by yourself.
Change sys.path by uncommenting existing line and change it to this:

sys.path.append(os.path.abspath('..'))

If you are not sure why why put .. there, it’s simple – Sphinx would go a one directory up (..) and try to find richtemplates there. Try to build your documentation now. Warning again? Yeah, Sphinx now complains about not
having DJANGO_SETTINGS_MODULE which is, again, totally correct. As importing richtemplates won’t
raise exception, but trying to get deeper into the module (richtemplates.forms) would be impossible without
being within Django context (same would happen if you try to run python interpreter and run from django import forms).
So add this line into your conf.py file:

os.environ['DJANGO_SETTINGS_MODULE'] = 'django.conf.global_settings'

More information about autodoc extension could be found here.

Hope this would help anyone trying to start with his/her own documentation :)
If you have any suggestions – let me know.

Take care and make documentation, not war.

• hg serve ( out of the box http server)
• it’s written in python
• has a very good eclipse plug-in (http://www.vectrace.com/mercurialeclipse/)

Cons: it’s slower than GIT ( but who cares :D )

So after installing mercurial and moving my svn repos with history with hgsvn ( which can also do push to svn )
I started to setup easy access to the repository using nginx. I’ll show you how to setup an SSL http based repository to do PUSH/PULL/CLONE what ever.

Firstly we have to make self signed ssl certificates.
I found on of the easiest tutorials available you can find it here: http://www.akadia.com/services/ssh_test_certificate.html

OK when we have the ssl certificates for our server. Put it somewhere on the server so nginx can access it.
We have to setup a new virtual host for nginx that will only do ssl connections
and have basic auth additionally.

Here’s the example config:

server {
    listen          443;
    server_name     hg.yourserver.com;
    ssl    on;
    ssl_certificate    /home/ssl_certs/hg_cert.crt;
    ssl_certificate_key     /home/ssl_certs/hg_cert.key;
    access_log      /var/log/nginx/hg.log;
    auth_basic      "mercurial server";
    auth_basic_user_file    /etc/nginx/.htpasswd;

    location / {
        proxy_pass      http://127.0.0.1:8001;
        #here's where the hg server runs
        include         /etc/nginx/proxy.conf;
    }
}

Few thing to notice.
.htpasswd file has to be in a format <username>:<cryptPassword> if you don’t have apache
installed you can use my password generator for generating crypt password. This username
and password will be used to do pull/push from console and eclipse.
Another important thing is that when you run hg serve you must specify the -a 127.0.0.1 option which is
for the address the mercurial server runs. Hg serve default is to start at all interfaces
so you have this port open outside and your ssl/passwd protection is for nothing…

I run my using hg serve –webdir-conf=/etc/hg/hgweb.conf -d -p 8001 -a 127.0.0.1

The hgweb.conf should be with

push_ssl = false
#since nginx is doing the SSL
allow_push = * #NGINX  is doing the auth
style = gitweb

O and one more thing remember that your repo should be accessible to hg serv.
I made a mistake and run hg serve as www-data and my repo was to my home user,
and i had internal server error when trying to do push to server.

So now you can have your repo via http with SSL and nginx authentication.

Download the Python-Threads pdf. Whitch includes the basic, and some more advanced information and tutorials about the threads in python.

In the pdf you can useful find info about:

• thread and threading modules
• queue
• locks
• gil
• events
• debugging threads

Found at http://www.lightbird.net/py-by-example/

I read many tutorials and sites dedicated to python, but this one is absolutely a must if you’re a python beginner. It’s loaded with simple examples, and descriptions. It briefly shows you the basics of python , each function is nicely explained with few examples. If you’re interested in learning Python this is the place to start. I personally found few things i did not use and know in python like shelve or inspect.

Here is the huge list of what’s on the page:

• String Services
  • String Module – Common string operations
  • Re Module – Regular expression operations
  • Struct Module – Interpret strings as packed binary data
  • Textwrap Module – Text wrapping and filling
• Data Types
  • Datetime.date Module – Basic date and time types
  • Calendar Module – General calendar-related functions
  • Array Module – Efficient arrays of numeric values
  • Sets Module – Unordered collections of unique elements
  • Pprint Module – Data pretty printer
• Numerical and Math Modules
  • Math Module – Mathematical functions
  • Decimal Module – Decimal fixed point and floating point arithmetic
  • Random Module – Generate pseudo-random numbers
• File and Directory Access
  • Os.path Module – Common pathname manipulations
  • Tempfile Module – Generate temporary files and directories
  • Shutil Module – High-level file operations
  • Glob Module – Unix style pathname pattern expansion
• Data Persistance
  • Pickle – Python object serialization
  • shelve – Python object persistence
  • sqlite3 – interface for SQLite databases
• Data Compression and Archiving
  • gzip – Support for gzip files
• File Formats
  • csv – CSV File Reading and Writing
  • ConfigParser – Configuration file parser
• Operating System Services
  • os – Operating system interfaces
  • Time Module – Time access and conversions
  • optparse – Command line option parser
  • logging – Logging facility for Python
  • Platform Module – Access to underlying platform identifying data
  • Rlcompleter Module – Completion function for GNU readline
• Python Runtime Services
  • Sys Module – System-specific parameters and functions
  • Traceback Module – Print or retrieve a stack traceback
  • Inspect Module – Inspect live objects

Regards M.