Commits

Stefan Scherfke  committed 17cb37b

Version 0.2, documentation

  • Participants
  • Parent commits 6b9d30a
  • Tags v0.2

Comments (0)

Files changed (10)

 a360a6472190eead2fd8647c76b67100cf166439 0.1
 ebf78dbc7887c0a4c3dc88522eca16cbdf7d211e 0.1.1
-050d3740c544e60582b0bcb58976072097e7e58b 0.2

File CHANGELOG.txt

 Changelog for django-sphinxdoc
 ==============================
 
+Version 0.2 – 2009-12-30:
+-------------------------
 
-Version 0.1 – 2009-?:
+- [NEW] Documentation, general index and module index work
+- [NEW] Basic documentation written
+
+
+Version 0.1 – 2009-12-19:
 -------------------------
 
 - [NEW] Initial release

File doc/autobuild.txt

+.. _autobuild:
+
+Auto-build JSON files on ``hg pull/push``
+=========================================
+
+If you use `Mercurial (hg) <http://selenic.com/mercurial/>`_ for the application
+you are documenting, you can automatically call ``sphinx-build`` each time you
+push or pull to the clone on your webserver (the same machine running
+your Django project).
+
+You need two things to accomplish this:
+
+1. A script that performs the build
+2. Make ``hg`` call that script
+
+The build script
+----------------
+
+A good place for the script is the ``.hg/`` directory of your repository on the server. Change to that directory and create a file called ``makedoc``:
+
+.. sourcecode:: bash
+
+    #! /bin/bash
+
+    cd /path/to/your/repo
+    hg up
+    cd /path/to/your/repo/doc
+    make json
+
+Make ``hg`` call that script
+----------------------------
+
+Open ``.hg/hgrc`` in your favorite editor and add the following lines to it:
+
+.. sourcecode:: cfg
+
+    [hooks]
+    changegroup = /path/to/your/repo/.hg/makedoc
+    
+Done
+----
+
+Now, each time the repository is modified via a pull or push command, the
+documentation will be updated automatically.

File doc/change_appearance.txt

+.. _change_appearance:
+
+Change your documentation’s appearance
+======================================
+
+The templates for ``django-sphinxdoc`` consist of of three top-level ``div``’s
+with the following classes:
+
+``pagination-top``
+    The upper pagination bar with breadcrumbs and links to the previous and
+    next section.
+    
+``sphinx``
+    The stuff generated by ``Sphinx``.
+    
+``pagination-bottom``
+    Like the upper pagination bar, but also contains the build date.
+    
+The ¶ sign after headings
+-------------------------
+
+To only show the headings’ ¶ sign, add something like this to your CSS:
+
+.. sourcecode:: css
+
+    #content .sphinx a.headerlink {
+        font-size: 0.8em; 
+        padding: 0 4px 0 4px; 
+        text-decoration: none; 
+        visibility: hidden;
+    }
+    #content .sphinx *:hover > a.headerlink { visibility: visible; }
+    
+    
+Changing font sizes for headings
+--------------------------------
+    
+Another style-problem for your site might be, that the Sphinx stuff starts with
+``h1`` as top level heading, but that your site uses ``h1`` for the site title
+and ``h2`` as top level content heading.
+
+I haven’t found a way to modify Sphinx’ behavior and make it use ``h2``. If you
+won’t change your behavior either, you can just change the font sizes of the
+Sphinx headings, so that Sphinx’ ``h1`` matches your ``h2``, e.g.:
+
+.. sourcecode:: css
+
+    h1 { font-size: 40px; } /* This is your blog title */
+    h2 { font-size: 22px; } /* This is used for page and post titles */
+    h3 { font-size: 18px; }
+    
+    /* Changes for Sphinx */
+    #content .sphinx h1 { font-size: 22px; }
+    #content .sphinx h2 { font-size: 18px; }
+    
+
+Changing the appearance of references and class names
+-----------------------------------------------------
+
+You can also change the appearance of references of class and method
+descriptions, e.g.:
+
+.. sourcecode:: css
+
+    #content .sphinx a.reference { text-decoration: none; }
+    #content .sphinx a.reference tt.literal {
+        border-bottom-width: 1px; 
+        border-bottom-style: dotted;
+    }
+    #content .sphinx a.reference em { font-style: normal; }
+
+    /* Smaller desc (default was 14px) and bold class name */
+    #content .sphinx .descclassname { font-size: 13px; }
+    #content .sphinx .descname { font-weight: bold; }
+    
+
+Other elements
+--------------
+
+It’s very easy to change the style of other elements. Just search for the
+elements and their CSS class names in the HTML output and add them to your CSS
+file. Remember to precede each style definition with ``#content .sphinx`` to
+avoid side effects to non-Sphinx stuff.
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

File doc/index.txt

     :maxdepth: 2
    
     quickstart
+    autobuild
+    change_appearance
     ref/index
 
+
 Indices and tables
 ==================
 

File doc/quickstart.txt

 .. _quickstart:
 
-Quickstart
-==========
+Quickstart Guide
+================
 
-*I have not written any documentation yet. Please be patient. ;-)*
+This guide assumes that you already have a `Django
+<http://www.djangoproject.com/>`_ installation up and running. If this is not
+the case, you should work through the `Django tutorial
+<http://docs.djangoproject.com/en/dev/intro/install/#intro-install>`_ first.
+
+
+Installation
+------------
+
+This app requires `Setuptools <http://pypi.python.org/pypi/setuptools>`_ for
+installation.
+
+You can either `download a stable version
+<http://bitbucket.org/scherfke/django-sphinxdoc/downloads/>`_ or use the latest
+version from the `repository <http://bitbucket.org/scherfke/django-sphinxdoc/src/>`_.
+
+If you downloaded the stable version, unpack it and open a terminal. Change to
+the directory that contains *django-sphinxdoc’s* ``setup.py`` and execute it as
+follows:
+
+.. sourcecode:: bash
+
+    $ cd where/you/put/django-sphinxdoc/
+    $ sudo python setup.py install
+    
+If you want the bleeding edge, clone the repository and install it in
+development mode. This will create just a link in your ``site packages`` that
+points to your local repository:
+
+.. sourcecode:: bash
+
+    $ hg clone http://bitbucket.org/scherfke/django-sphinxdoc/
+    $ cd django-sphinxdoc/
+    $ sudo python setup.py develop
+    
+With this done, all you need to do to upgrade your installation of
+*django-sphinxdoc* is to type:
+
+.. sourcecode:: bash
+
+   $ hg pull -u
+
+
+Setup
+-----
+
+Add ``'sphinxdoc'`` to your ``INSTALLED_APPS`` within your 
+``settings.py`` and add the following line to your project’s ``urls.py``:
+   
+.. sourcecode:: python
+
+    (r'^docs/', include('sphinxdoc.urls')),
+    
+Install the required database table with:
+
+.. sourcecode:: bash
+
+    python manage.py syncdb
+    
+    
+Add an application
+------------------
+
+If you visit your project’s admin panel, you’ll find the new application
+*Sphinxdoc* with the *App* model. If you add a new app, you’ll need to fill
+three form fields:
+
+Name:
+    The name of the documented application
+    
+Slug:
+    A sluggified version of the application name; will be generated
+    automatically
+
+Path:
+    A file system path to the JSON files generated by Sphinx including
+    ``_build/json/``, e.g.: ``/path/to/app/doc/_build/json/``
+
+
+That’s it!
+----------
+
+You can now find the application’s documentation under */docs/<slug>/*.
+
+You may want to read:
+
+* :ref:`autobuild`
+* :ref:`change_appearance`
 
 
 setup(name='django-sphinxdoc',
-    version=lastfm.__version__,
+    version=sphinxdoc.__version__,
     description='Easily integrate Sphinx documentation into your website.',
     author='Stefan Scherfke',
     author_email='',

File sphinxdoc/__init__.py

+# encoding: utf-8
+
+__version__ = '0.2'

File sphinxdoc/templates/sphinxdoc/documentation.html

 {% extends 'base.html' %}
 
-{% block title %}{{ block.super }} » {{ doc.title|striptags|safe }}{% endblock %}
+{% block title %}{{ block.super }} » {{ app.name }}{% for p in doc.parents %} » {{ p.title|striptags|safe }}{% endfor %} » {{ doc.title|striptags|safe }}{% endblock %}
 
 {% block content %}
 <div class="pagination-top">
-    » <a href="{{ app.get_absolute_url }}">{{ app.name }} documentation</a>
+    » <a href="{{ app.get_absolute_url }}">{{ app.name }}</a>
     {% for p in doc.parents %}
     » <a href="{{ p.link }}">{{ p.title|safe }}</a>
     {% endfor %}