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
$ vagrant up
After that vagrant ssh can be used to connect to the Virtual Machine.
The files in the requirements directory contain all Python packages needed to extend, test and build the tutorial.
The following command installs all necessary requirements (you may want to use a virtualenv for that):
$ make install
To deploy django-marcador, prepare translations and make HTML and PDF builds easier you can use Fabric.
This lists all available Fabric commands:
$ fab -l
To get more information about the options for a single command use:
$ fab -d <command>
How to build the tutorial
Beside the Python Packages listed in the requirements files 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:
$ make -C docs clean doctest linkcheck html
You can also build a PDF:
$ make -C docs 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 capture screenshots
All screenshots can be taken automatically using the capture.js script. CasperJS is required to run the script. There are several Makefile targets to capture the screenshots. For each target a runserver from a different directory has to be started, so that the right screens are captured.
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 = django-marcador.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 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.
Source Code License
Copyright (c) 2012-2015, 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.