django-marcador is a Django tutorial. It shows how to build a bookmark app using Django. Currently English, German and Spanish translations are available.
The tutorial is hosted at http://django-marcador.keimlink.de.
How to edit the tutorial
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
Beside the Python Packages listed in requirements.txt you will need the following software to be able to build the tutorial:
Build using make
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
Build using Fabric
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
The translation workflow is as follows:
- Edit the tutorial
- Create a pull request
- Wait until your pull request has been accepted and the sources on Transifex have been updated
- Create or update the translations on Transifex
- The new translations will be pulled from Transifex into the repository
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 English.
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=de_DE
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:
- Run the test suite of the django-marcador app
- Clean up the Sphinx build directory
- Run Sphinx doctests
- Build the HTML files
- 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
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: >>> settings.LOGIN_URL == 'mysite_login' True >>> settings.LOGOUT_URL == 'mysite_logout' True >>> settings.LOGIN_REDIRECT_URL == '/' 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
All links should be created as inline links:
Named hyperlink targets like shown below do not work with gettext so please don't use them:
`Python`_ .. _Python: http://python.org/
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:
Link to a RFC using the :rfc: role:
Use :envvar: for environment variables:
the environment variable :envvar:`%PATH%`
Use the :file: role for directories and files:
Use the :program: role for programs:
Use the :option: role for program options:
Start the program :program:`python` using the :option:`-V` option.
Notes are added like this:
.. 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.
This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.
Source Code License
Copyright (c) 2012, Markus Zapke-Gründemann All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the names of the authors nor the names of other contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.