Contributing to the Pylons documentation

How to get a clone of the Pylons mercurial repository. How to run Sphinx to generate the Pylons documentation. How to add changes, additions to the Pylons repository clone. How to create mercurial bundles from changes made to the cloned repository for submitting as contributions to the Pylons team.

Getting a copy of the latest sources

Step one is to install Mercurial.

Once installed, the commmand-line function hg will be available.

Following the instructions on the Pylons wiki, obtain a copy of the current sources of Pylons by using hg clone.

When making just a few ad hoc changes to code in a Mercurial repository, the standard procedure is to to clone a repository, make the changes, create a bundle of those changes for merging into the repository. After the changes have been merged it is common practice to delete the clone.

Obtaining a copy of the Pylons source code, which includes the documentation in restructuredText format:

$ hg clone https://www.knowledgetap.com/hg/pylons-dev pylons-dev

Documentation is in language-specific directories:

$ cd pylons-dev/pylons/doc/en

Making changes, adding documents, etc.

The next step is to make the intended changes; additions, amendments, corrections, etc.

In order to view the changes as rendered into HTML, take recourse to the command-line:

$ make
Please use `make <target>' where <target> is one of
  html      to make standalone HTML files
  web       to make files usable by Sphinx.web
  htmlhelp  to make HTML files and a HTML help project
  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  changes   to make an overview over all changed/added/deprecated items
  linkcheck to check all external links for integrity
$ make html

The rendered pages of HTML are in _build/html, relative to the pylons/doc/uk directory.

If the rendering is satisfactory, the next step is to add the changes to the repository.

Adding to and updating the local clone of the Pylons repository.

Entering hg status on the command line will list the status of the changes to the repository:

$ hg status
M pylons/docs/uk/index.rst
? pylons/docs/uk/doc_contribs.rst

The status report indicates that the doc_contribs.rst needs to be added to the repository clone (which is now acting as the working repository). The hg add command adds all new files in the current working directory and below. Alternatively, additions can be limited by providing one or more filenames as arguments:

$ hg add doc_contribs.rst

For sanity’s sake, check the status again:

$ hg status
M pylons/docs/uk/index.rst
A pylons/docs/uk/doc_contribs.rst

Commit the changes (to the working repository). A commit instruction also silently creates a new “changeset” for later reference. The provision of an informative commit message will be appreciated by others:

$ hg commit -m "Adding documentation for contributors to the documentation"

Check the status, just to be sure:

$ hg status

No news is good news. The (local version of the) repository has been updated and is in a state ready for the changes to be extracted and bundled for merging into the main repository.

Creating a bundle of changesets ready for despatch

Create a bundle of all of the new changesets.:

$ hg bundle doc_contribs.bundle
searching for changes
1 changesets found

Check that there was a result:

$ ls -al doc_contribs.bundle
-rw-r--r--  1 httpd  staff  1449 10 Jan 04:13 doc_contribs.bundle

Effecting the contribution

Attach the bundle to an email to the Pylons team or raise a ticket and attach the bundle to the ticket.

After the changeset(s) in the bundle have been applied to the main repository, commit messages will appear in the list of applied changesets in the repository changelog