Hierarchy & Structure

[sophshep]

I need Dev help to set up the navigation & pages on our new sphinx build to match those of the support taxonomy doc: https://docs.google.com/document/d/1mabJN8S5FNYlS0EQ5Cm-hNNcBxPLHcc6BmN79RqpTpw/edit

cc @rjmackay @willdoran @jshorland

[willdoran]

hey @sophshep I can certainly try to help out, let me know what you need.

[sophshep]

Thanks @willdoran! @rjmackay set up the basic build on the rtd-sphinx branch. I'm currently working through theming it, but setting up the structure is beyond me. I believe that currently it just has existing content that Robbie brought over, which is quite messy. What I'd like to do is organize it to match the document above. Each page can have dummy content or just be empty. Then the comms team can enter content into a fresh system via GitHub.

[willdoran]

@sophshep: Ok, groovy. I'll pull down the repo, peruse it and figure out how to get the structure to fit the doc. I'll update you when I have it together.

[willdoran]

@sophshep
Hopefully this is ok, i pushed up a commit with a slightly different ToC to act as a guide.

Ok - stop me if this is the not what you're looking for or you've already got this bit:
To install run:
pip install sphinx
(you may need this)pip install recommonmark
from docs.ushahidi.com dir run:
make html -> this will generate a build dir showing the output of the existing source
Between builds the build/ dir doesn't seem to be overwritten this can lead to inconsistency so before make the html again it might be worth deleting the dir.

In order to match the ToC structure from the doc it is necessary to edit the index.rst file. This is the landing page. For example, the section

Getting started with Ushahidi
-Concepts of Ushahidi
-Examples of Deployments
-Link to deployments of the week
-Questions to ask before you deploy
-Create a new deployment
-Ushahidi Mobile Apps

Would become in the index.rst file:

.. toctree::
    :maxdepth: 1

     getting-started/index

In the getting-started dir, an index.rst should be created linking out to the subpages

getting-started/index.rst:

Getting started with Ushahidi
=======================

.. toctree::
    maxdepth: 1

    concepts-of-ushahidi
    examples-of-deployments

That is one option, it is also possible to create a single file called getting-started.rst and to create sub-heading with in it.

A good example for that approach is the guzzle docs:
http://guzzle.readthedocs.org/en/5.3/index.html
and their source:
https://github.com/guzzle/guzzle/tree/5.3/docs

Let me know if that was any help or just made things worse!