django-marcador /

Filename Size Date modified Message
.tx
docs
packer
requirements
salt
src
static
79 B
Add tox.ini to simplify testing with different environments
605 B
Added tag 1.4.1 for changeset ad45eb071f6d
1.3 KB
Added tox requirement and a "install" task
9.6 KB
Upgraded to Creative Commons 4.0 (fixing #83)
1.1 KB
Enabled NFS for Vagrant synced folder (VMWare only)
14.7 KB
Added diff Fabric tasks
163 B
Upgraded to Python 3.4

django-marcador

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.

If you want to discuss new ideas, problems or anything else regarding django-marcador use our Librelist mailing list and simply write to djangomarcador@librelist.com.

How to edit the tutorial

A Vagrantfile and a Packer template for a Debian box are included and can be used to create a Virtual Machine to work with the tutorial. Simply create the Virtual Machine by running:

$ vagrant up

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.

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

Requirements

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 translations are maintained using Transifex. If you want to help with the translation please contact us so you can be added to the django-marcador project on Transifex.

The translation workflow is as follows:

  1. Edit the tutorial
  2. Create a pull request
  3. Wait until your pull request has been accepted and the sources on Transifex have been updated
  4. Create or update the translations on Transifex
  5. 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:

  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:

    >>> 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:

`Python <http://python.org/>`_

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:

: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.

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.

Documentation License

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, 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.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.