Improve docs

django-wiki · May 6, 2016 · a3aa816 · a3aa816
1 parent 7c0cbe9
commit a3aa816
Show file tree

Hide file tree

Showing 7 changed files with 49 additions and 35 deletions.
diff --git a/README.rst b/README.rst
@@ -241,15 +241,13 @@ Q&A
 Requirements
 ------------
 
-So far the dependencies/requirements are:
-
 -  `django>=1.5<1.7 <http://www.djangoproject.com>`__ - Django 1.7 will
    be released in version 0.1, but should run on 0.0.24
 -  `django-south <http://south.aeracode.org/>`__
 -  `Markdown>=2.2.0 <https://github.com/waylan/Python-Markdown>`__
 -  `django-mptt <https://github.com/django-mptt/django-mptt>`__
 -  `django-sekizai <https://github.com/ojii/django-sekizai/>`__
--  `sorl-thumbnail <https://github.com/sorl/sorl-thumbnail>`__
+-  `sorl-thumbnail <https://github.com/mariocesar/sorl-thumbnail>`__
 -  Pillow (Python Imaging Library)
 -  Python>=2.6 or Python>=3.2
 

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -1,6 +1,24 @@
 FAQ
 ===
 
+Q: Why can't I move articles?
+-----------------------------
+
+A: Moving articles is not trivial. Here are a couple of reasons:
+
+ * Other articles may link to them.
+ * Permissions may change if you move the articles into a different hierarchy
+ * We keep revisions of stuff, so the action of moving an article will create a new revision.
+ * ...but what if the revision is reverted and we had automatically renamed stuff?
+
+Because it isn't trivial to move articles, the work has delayed somewhat.
+
+Resources:
+
+ * `Pull Request #461 <https://github.com/django-wiki/django-wiki/pull/461>`__
+ * `Issue #154 <https://github.com/django-wiki/django-wiki/issues/154>`__
+
+
 Q: Why do I keep getting *"This slug conflicts with an existing URL."*
 ----------------------------------------------------------------------
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,18 +6,17 @@
 A wiki for Django!
 ==================
 
-Contents:
-
 .. toctree::
+   :caption: Contents
+   :name: mastertoc
    :maxdepth: 2
 
    installation
    plugins
    customization
    settings
-   tips
+   tips/index
    release_notes
-   known_issues
    faq
    history
    todo

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -5,7 +5,7 @@ Pre-requisites
 --------------
 
 For image processing, django-wiki uses the `Pillow
-library <https://github.com/python-imaging/Pillow>`_ (a fork of PIL).
+library <https://github.com/python-pillow/Pillow>`_ (a fork of PIL).
 The preferred method should be to get a system-wide, pre-compiled
 version of Pillow, for instance by getting the binaries from your Linux
 distribution repos.
@@ -140,7 +140,7 @@ Configure ``TEMPLATE_CONTEXT_PROCESSORS``
 Add ``'sekizai.context_processors.sekizai'`` and
 ``'django.core.context_processors.debug'`` to
 ``settings.TEMPLATE_CONTEXT_PROCESSORS``. Please refer to the `Django
-docs <https://docs.djangoproject.com/en/dev/ref/settings/#template-context-processors>`_
+settings docs <https://docs.djangoproject.com/en/dev/ref/settings/>`_
 to see the current default setting for this variable.
 
 In Django 1.5, it should look like this:

diff --git a/docs/known_issues.rst b/docs/known_issues.rst
diff --git a/docs/release_notes.rst b/docs/release_notes.rst
@@ -31,18 +31,18 @@ break due to some force majeure.
 django-wiki 0.1.1
 -----------------
 
-New features:
-
  * Several languages updated from Transifex
-   * Slovak added [Thanks M Hozza]
+
+   * Slovak added **Thanks M Hozza**
    * Portuguese also added, but as copy of PT-BR (make changes as desired in Transifex)
- * Brand new Account Settings page (email / password) - Thanks: inflrscns
+
+ * Brand new Account Settings page (email / password) **Thanks inflrscns**
  * Testproject turned into Django 1.9 layout
- * Do not depend on STATIC_URL anymore, use {% static %}
+ * Replace context-processor dependent use of ``{{ STATIC_URL }}`` with ``{% static %}``
  * Bugfix for ``pip install wiki`` in an empty (no Django installed) virtualenv
  * Precommit hooks added in repository
  * Import statements sorted and codebase re-pep8'thed
- * Log in page is now called "Log in" in ``<title>`` tag - Thanks: Eugene Obukhov
+ * Log in page is now called "Log in" in ``<title>`` tag - **Thanks Eugene Obukhov**
 
 
 django-wiki 0.1

diff --git a/docs/tips.rst → docs/tips/index.rst b/docs/tips.rst → docs/tips/index.rst
@@ -1,5 +1,13 @@
-Other tips
-==========
+Tips
+====
+
+.. toctree::
+   :caption: Tips index
+
+   disqus
+
+Quick tips
+----------
 
 1. **Account handling:** There are simple views that handle login,
    logout and signup. They are on by default. Make sure to set
@@ -9,7 +17,15 @@ Other tips
 2. **Syntax highlighting:** Python-Markdown has a pre-shipped codehilite
    extension which works perfectly, so add something like::
 
-       WIKI_MARKDOWN_KWARGS = {'extensions': ['footnotes', 'attr_list', 'headerid', 'extra', 'codehilite', ]}
+       WIKI_MARKDOWN_KWARGS = {
+           'extensions': [
+               'footnotes',
+               'attr_list',
+               'headerid',
+               'extra',
+               'codehilite',
+           ]
+       }
 
    to your settings. Currently, django-wiki ships with a stylesheet
    that already has the syntax highlighting CSS rules built-in. Oh, and
@@ -18,5 +34,3 @@ Other tips
 
 3. **Project Templates:** Create new django-wiki projects quickly and easily using django-wiki project templates
    https://github.com/django-wiki/django-wiki-project-template
-
-4. **Disqus comment embed:** See :doc:`this page</tips/disqus>`