From a3aa8168631bb891145c9109d4cab5d25e38e1c8 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 6 May 2016 12:48:16 +0200 Subject: [PATCH] Improve docs --- README.rst | 4 +--- docs/faq.rst | 18 ++++++++++++++++++ docs/index.rst | 7 +++---- docs/installation.rst | 4 ++-- docs/known_issues.rst | 15 --------------- docs/release_notes.rst | 12 ++++++------ docs/{tips.rst => tips/index.rst} | 24 +++++++++++++++++++----- 7 files changed, 49 insertions(+), 35 deletions(-) delete mode 100644 docs/known_issues.rst rename docs/{tips.rst => tips/index.rst} (72%) diff --git a/README.rst b/README.rst index 1e80d203..9ebbbb6c 100644 --- a/README.rst +++ b/README.rst @@ -241,15 +241,13 @@ Q&A Requirements ------------ -So far the dependencies/requirements are: - - `django>=1.5<1.7 `__ - Django 1.7 will be released in version 0.1, but should run on 0.0.24 - `django-south `__ - `Markdown>=2.2.0 `__ - `django-mptt `__ - `django-sekizai `__ -- `sorl-thumbnail `__ +- `sorl-thumbnail `__ - Pillow (Python Imaging Library) - Python>=2.6 or Python>=3.2 diff --git a/docs/faq.rst b/docs/faq.rst index a8f36bbc..7c2f7f77 100644 --- 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 `__ + * `Issue #154 `__ + + Q: Why do I keep getting *"This slug conflicts with an existing URL."* ---------------------------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 97ebedf2..13e4e0b8 100644 --- 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 index 3bd9e930..0d922777 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -5,7 +5,7 @@ Pre-requisites -------------- For image processing, django-wiki uses the `Pillow -library `_ (a fork of PIL). +library `_ (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 `_ +settings docs `_ 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 deleted file mode 100644 index 855deb16..00000000 --- a/docs/known_issues.rst +++ /dev/null @@ -1,15 +0,0 @@ -Known Issues -============ - -Django 1.4 ----------- - -1.4.2+ - -* In the requirements is stated ``sorl-thumbnail>11.12.1b`` which is the newest beta of sorl-thumbnail. However, you need to downgrade after. -* [django-mptt issue #271](https://github.com/django-mptt/django-mptt/issues/271) means that you should use Django 1.4.2+. - -Django 1.7+ and Python 2.6 --------------------------- - -Those are incompatible with each other and can never be combined as Dj 1.7 dropped Py 2.6 support. diff --git a/docs/release_notes.rst b/docs/release_notes.rst index 1f256988..56913ee8 100644 --- 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 ```` 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 b/docs/tips/index.rst similarity index 72% rename from docs/tips.rst rename to docs/tips/index.rst index dde8d0b3..5de55944 100644 --- a/docs/tips.rst +++ b/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>` \ No newline at end of file -- 2.45.2