Overview

django-marcador is a German Django tutorial. It shows how to build a bookmark app using Django.

A Vagrantfile and definitions for a Debian box are included and can be used to create a virtual machine to build the app.

The requirements.txt file contains all Python packages needed to extend, test and build the tutorial.

Install the requirements with the following command (you may want to use a virtualenv for that):

$pip install -r requirements.txt  To deploy django-marcador, prepare translations and make HTML and PDF builds easier you can install Fabric: $ pip install fabric


You can list all Fabric tasks with the following command:

$fab -l  To get more information about the options for a single task use: $ fab -d TASK


How to build the tutorial

To run the basic tests and build the HTML files use the Makefile in the docs directory:

$cd docs$ make clean doctest linkcheck html


You can also build a PDF (still in the docs directory):

$make clean doctest linkcheck latexpdf  If you have installed Fabric you can use the build task to create (and open) the HTML files: $ fab build


There is also a task to create (and open) the PDF:

$fab build_pdf  How to prepare, create and update translations We are using gettext to create and maintain the message files. You have to install gettext to create or update the message files. You will also need gettext to build the tutorial in a language different from German. If you just want to help translating existing message files you don't need gettext. To prepare the translations you have to create the *.po files. The Fabric task make_messages does this. You have to specify the language of the translation with the language argument: $ fab make_messages:language=en_US


The build, build_pdf and deploy tasks take a language argument to build or deploy not the default language.

Every time the documentation sources have been edited you need to run the make_messages command again to update the translations.

How to deploy the tutorial

If you want to deploy the HTML files to a server you can use the Fabric deploy task that comes with django-marcador:

$fab deploy:/path/where/static/files/go  The deploy task will perform the following steps before the actual deployment: 1. Run the test suite of the django-marcador app 2. Clean up the Sphinx build directory 3. Run Sphinx doctests 4. Build the HTML files 5. Run Sphinx linkcheck If you want to make deployment with Fabric easy repeatable you can use a fabricrc file like this: user = alice host_string = slides.example.com remotepath = /path/where/static/files/go  And then use it like so: $ fab -c fabricrc deploy


Contributions and Bugs

Feel free to improve django-marcador or create translations. Pull requests are welcome!

Please report problems to our issue tracker.

How to contribute

The documentation is using Sphinx, so reStructuredText and Sphinx-specific markup should be used to write the documentation.

All documentation is inside the docs directory. All code is inside the src directory.

If you want to display any code in the documentation use the literalinclude:: role:

.. literalinclude:: ../src/mysite/marcador/views.py
:lines: 2, 5-6, 8-24
:linenos:
:emphasize-lines: 1, 13-20


In general you should write unit tests for the code to make sure it works.

In some edge cases you can use the doctest:: role to write simple doctest for includes:

.. literalinclude:: ../src/mysite/mysite/settings.py
:lines: 159-161
:linenos:

.. doctest::
:hide:

True
>>> settings.LOGOUT_URL == '/logout/'
True
True


Limit all lines to a maximum of 72 characters (PEP 8). Lists are the only exception.

Create headings using the following hierarchy:

• * with overline, for chapters
• =, for sections
• -, for subsections
• ^, for subsubsections
• ", for paragraphs

Use extlinks to link to the Django documentation or to the issue tracker:

See the :djangodocs:shortcuts documentation <topics/http/shortcuts/#example>.

Made Bookmark.tags optional (fixing :issue:9)


Use the :doc: role to link to other pages of the documentation:

Removed obsolete line from URLconf in :doc:admin_syncdb


Use the index: role to add a section to the index:

.. index:: Manager, Models, Object Relational Mapper, ORM

Model Creation
==============


Link to PEPs using the :pep: role:

:pep:8


Link to a RFC using the :rfc: role:

:rfc:2616


Use :envvar: for environment variables:

the environment variable :envvar:%PATH%


Use the :file: role for directories and files:

:file:C:\\Python27\\

:file:mysite/settings.py


Use the :program: role for programs:

:program:pip


Use the :option: role for program options:

Start the program :program:python using the :option:-V option.


..  note::

This is a note.


Use the :menuselection: and guilabel: roles for menu items and other elements like buttons:

:menuselection:Start --> Settings --> Control Panel

Click on the :guilabel:Environment Variables button.


Use the :kdb: role for keystrokes:

:kbd:STRG + C


See the Sphinx inline markup documentation for more markup roles.