From 1522c4c3c67a052dc1e1d0a0ada0a86314224599 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 16 Dec 2013 17:35:54 +0100 Subject: [PATCH] Add a couple of notes to the documentation guidelines --- doc/contributing/documentation.rst | 33 ++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/contributing/documentation.rst b/doc/contributing/documentation.rst index 332a4d165ad..c902ef77941 100644 --- a/doc/contributing/documentation.rst +++ b/doc/contributing/documentation.rst @@ -151,6 +151,39 @@ suggestion for what sections the page should have is: diagnose problems. +Subdirectories +============== + +Many sections of the docs are organized into subdirectories. For example, +there's a ``doc/extensions`` subdirectory with +:doc:`its own index file ` and table of contents, grouping +all the docs about extensions together into one topic. The +:doc:`contributing docs `, theming docs, and other +sections of the docs are the same. + +While using subdirectories is useful, we recommend that you +**don't put further subdirectories inside the subdirectories**, keep it to +one level of subdirectories inside the ``doc`` directory, keep it simple, +otherwise the structure becomes confusing, difficult to get an overview of and +difficult to navigate. + + +Linear ordering +=============== + +Keep in mind that Sphinx requires the docs to have a simple, linear ordering. +With HTML pages it's possible to design structure where, for example, someone +reads half of a page, then clicks on a link in the middle of the page to go +and read another page, then goes back to the middle of the first page and +continues reading where they left off. While technically you can do this in +Sphinx as well, it isn't a good idea, things like the navigation links, table +of contents, and PDF version will break, users will end up going in circles, +and the structure becomes confusing. + +So the pages of our Sphinx docs need to have a simple linear ordering - one +page follows another, like in a book. + + .. _style: --------