Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Reviewed new Sphinx docs section

  • Loading branch information...
commit 1b862ec44162c64d9fccb10c587ba5d9865af09c 1 parent 7ce01d2
@dbunskoek dbunskoek authored
View
2  docs/.gitignore
@@ -1 +1 @@
-build
+_build
View
153 docs/Makefile
@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-fiber.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-fiber.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/django-fiber"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-fiber"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
View
1  docs/__init__.py
@@ -1 +0,0 @@
-# keep spinx happy while loading doc_settings for Django.
View
22 docs/advanced-usage.rst
@@ -6,8 +6,8 @@ Advanced usage
This document is used to gather more advanced usage examples.
-Optional settings:
-==================
+Optional settings
+=================
These settings are optional (default values are shown):
@@ -37,8 +37,8 @@ These settings are optional (default values are shown):
API_RENDER_HTML = False # If set to True, you must include 'djangorestframework' in INSTALLED_APPS as well
-Set or override fiber_page in the view:
-=======================================
+Set or override fiber_page in the view
+======================================
In this example, the news_item_detail view looks up the Page of the news_item_list by looking up its named URL. This way, you can reuse the content you have placed on the news_item_list Page for each news_item_detail Page.
@@ -57,8 +57,8 @@ In this example, the news_item_detail view looks up the Page of the news_item_li
return HttpResponse(t.render(c))
-Set or override fiber_page in the classed based view:
-=====================================================
+Set or override fiber_page in the classed based view
+====================================================
In this example, the NewsItemDetailView's context is enriched with fiber_page and fiber_current_pages.
@@ -75,8 +75,8 @@ In this example, the NewsItemDetailView's context is enriched with fiber_page an
return reverse('news_item_list')
-Templates:
-==========
+Templates
+=========
In this example 4 page-templates will be available in the front- and backend-admin:
@@ -104,8 +104,8 @@ In this example 2 content-templates will be available in the front- and backend-
The first choice '' will load the default content-template, this is 'fiber/content_item.html'
-Metadata:
-=========
+Metadata
+========
In this example metadata (key-value pairs) for pages will be available in the backend-admin:
@@ -185,7 +185,7 @@ https://github.com/ridethepony/django-fiber/blob/master/fiber/static/fiber/js/fi
Custom permissions
==================
-Fiber provides a :mod:`fiber.permissions` module. The Permission class defined here can be overridden by writing a custom
+Fiber provides a :mod:`fiber.permissions` module. The Permission class defined here can be overridden by writing a custom
permission class and pointing `PERMISSION_CLASS` in your settings module to that class.
Here's an example module that implements object level permissions:
View
18 docs/conf.py
@@ -11,7 +11,9 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
-import sys, os
+import sys
+import os
+from datetime import datetime
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@@ -19,9 +21,9 @@
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
-import doc_settings
+import docs_settings
from django.core.management import setup_environ
-setup_environ(doc_settings)
+setup_environ(docs_settings)
# -- General configuration -----------------------------------------------------
@@ -30,7 +32,7 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -46,7 +48,7 @@
# General information about the project.
project = u'django-fiber'
-copyright = u'2012, Ride The Pony'
+copyright = u'%d, Ride The Pony' % datetime.today().year
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -70,7 +72,7 @@
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
@@ -97,7 +99,7 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'sphinxdoc'
+html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -126,7 +128,7 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
View
2  docs/contributors.rst
@@ -2,4 +2,4 @@
Contributors
============
-.. literalinclude:: authors
+.. literalinclude:: contributors.txt
View
27 docs/authors → docs/contributors.txt
@@ -1,22 +1,15 @@
-Dennis Bunskoek <dbunskoek@leukeleu.nl>
-Michael van de Waeter <mvdwaeter@gmail.com>
-Bram Simons <info@simons-design.nl>
-Marko Tibold <marko@tibold.nl>
-Marko Tibold <mtibold@leukeleu.nl>
Bart Heesink <bheesink@leukeleu.nl>
-Marco Braak <mbraak@ridethepony.nl>
-Diederik van der Boor <vdboor@edoburu.nl>
-mvdwaeter <mvdwaeter@gmail.com>
-Niels van Dijk <nvandijk@leukeleu.nl>
Bram Simons <bsimons@leukeleu.nl>
-Selwin Ong <selwin@ui.co.id>
-Nick Badoux <nbadoux@leukeleu.nl>
Chi Shang Cheng <cscheng@leukeleu.nl>
-michael <michael@samarium.leukeleu.nl>
+Dennis Bunskoek <dbunskoek@leukeleu.nl>
+Diederik van der Boor <vdboor@edoburu.nl>
+Douwe van der Meij <vandermeij@gw20e.com>
Dzjon Hessing <dhessing@ridethepony.nl>
-cscheng <cscheng@leukeleu.nl>
-Selwin Ong <selwin.ong@gmail.com>
-Maarten Draijer <maarten@madra.nl>
Luke Plant <L.Plant.98@cantab.net>
-Douwe van der Meij <vandermeij@gw20e.com>
-dbunskoek <dbunskoek@leukeleu.nl>
+Maarten Draijer <maarten@madra.nl>
+Marco Braak <mbraak@ridethepony.nl>
+Marko Tibold <mtibold@leukeleu.nl>
+Michael van de Waeter <mvdwaeter@gmail.com>
+Nick Badoux <nbadoux@leukeleu.nl>
+Niels van Dijk <nvandijk@leukeleu.nl>
+Selwin Ong <selwin.ong@gmail.com>
View
11 docs/doc_settings.py
@@ -1,11 +0,0 @@
-# Mocl settings file imported by sphinx when building docs
-# for python code that loads Django
-
-DATABASES = {
- 'default': {
- 'ENGINE': 'django.db.backends.sqlit3',
- 'NAME': 'foo.sqlite',
- }
-}
-
-SECRET_KEY = 'foo'
View
3  docs/docs_settings.py
@@ -0,0 +1,3 @@
+# Mock settings file imported by sphinx when building docs
+
+SECRET_KEY = 'not empty'
View
6 docs/index.rst
@@ -3,8 +3,8 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to django-fiber's documentation!
-========================================
+Welcome to django-fiber's documentation
+=======================================
This is the documentation project for django-fiber.
@@ -13,7 +13,7 @@ Contents
.. toctree::
:maxdepth: 2
-
+
usage
advanced-usage
contributors
View
5 docs/make_contributors.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# regenerate contributors.txt from git contributors
+# be sure to remove duplicates
+git log --pretty='%aN <%aE>' | sort | uniq > contributors.txt
View
4 docs/make_docs.sh
@@ -1,3 +1,3 @@
#!/bin/bash
-git log --format='%aN <%aE>' | awk '{arr[$0]++} END{for (i in arr){print arr[i], i;}}' | sort -rn | cut -d\ -f2- > authors
-sphinx-build -E . build
+
+sphinx-build -E . _build
View
2  docs/settings.rst
@@ -1,5 +1,5 @@
:mod:`app_settings`
-=====================
+===================
:ref:`advanced_usage_custom_permissions`
View
4 docs/usage.rst
@@ -3,8 +3,8 @@ Usage
=====
-Usage instructions:
-===================
+Usage instructions
+==================
Page tree
Please sign in to comment.
Something went wrong with that request. Please try again.