*************** 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 If you want to discuss new ideas, problems or anything else regarding django-marcador use our `Librelist <>`_ mailing list and simply write to How to edit the tutorial ======================== A `Vagrantfile <>`_ for a `Debian <>`_ box is included and can be used to create a Virtual Machine to work with the tutorial. Simply create the Virtual Machine by running:: $ 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 ========================= Requirements ------------ Beside the Python Packages listed in the ``requirements`` files you will need the following software to be able to build the tutorial: - `Graphviz <>`_ - `LaTeX <>`_ (for the PDF version) - `CasperJS <>`_ (to capture the screenshots) 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: #. 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 = 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/ :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/ :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 <>`_ Named hyperlink targets like shown below do not work with ``gettext`` so **please don't use them**:: `Python`_ .. _Python: 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/` 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 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.