Use of shocco not documented

[Adam Spiers]

devstack uses shocco to generate HTML docs, but the exact steps do not seem to be documented anywhere. It would be helpful to document this so that developers can help ensure that the HTML docs produced are correct.

For example, I noticed that http://devstack.org/lib/ceilometer.html contains an error:

    System Message: ERROR/3 (<stdin>, line 4)

    Unexpected indentation.

which I wanted to fix. Upon further investigation, I found that this error comes from docutils and that rst2html was required in order to mimic the process used for generation on devstack.org.

I'm also guessing that this fork of shocco is required but I'm not sure:

    https://github.com/dtroyer/shocco/compare/rst_support

If so, it would be great if a pull request was issued for this against the upstream shocco.

Finally, I got it working by configuring the MARKDOWN variable in shocco to use the markdown executable from the Python-based Markdown 2.2.1 implementation.

[Adam Spiers (adam.spiers)]

Once I had it working, I fixed all shocco warnings and errors:

https://review.openstack.org/#/c/49872/

However I think whatever process is used to automatically generate the online docs (a Jenkins job?) needs to be tweaked in order to barf if when any future commit introduces new warnings/errors to shocco. If we can get this into the gate then we'll never have to retroactively fix them in the future. Please let me know if you would like me to file a separate bug for this gate work. Thanks!

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/52514
Committed: http://github.com/openstack-dev/devstack/commit/b8dd27bf457d1c7a7ad0f1b3a946529c8a1d073f
Submitter: Jenkins
Branch: master

commit b8dd27bf457d1c7a7ad0f1b3a946529c8a1d073f
Author: Dean Troyer <email address hidden>
Date: Thu Oct 17 12:03:55 2013 -0500

    Fix typos and thinkos in docs

    Updates for the new major features and some clarification

    Partial-Bug: #1235626

    Change-Id: If2da63e62a14894e498b4163b5052d9b2b2069ed

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/havana
Review: https://review.openstack.org/53214

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/52226
Committed: http://github.com/openstack-dev/devstack/commit/9b973670a6c200e5f6251bb21eb443be619694c6
Submitter: Jenkins
Branch: master

commit 9b973670a6c200e5f6251bb21eb443be619694c6
Author: Dean Troyer <email address hidden>
Date: Wed Oct 16 15:13:56 2013 -0500

    Add the doc build tools

    tools/build_docs.sh generates the devstack.org website from the static
    pages and generated pages created by running shocco against a DevStack
    checkout.

    Note that while this is the complete auto page generation of the
    devstack.org site, pushing the content back to GitHub is limited
    to those with push access to the current repo.

    Partial-bug 1235626

    Change-Id: I61dc3d56e4a4832a9ddd1904dd8af65c15a17e50

[Adam Spiers (adam.spiers)]

I have submitted https://github.com/rtomayko/shocco/pull/33 and https://github.com/rtomayko/shocco/pull/34 which will get the changes we need upstream.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/53214
Committed: http://github.com/openstack-dev/devstack/commit/7f9bdc47c8318a8c6d681a3fd229bf30348ecbce
Submitter: Jenkins
Branch: stable/havana

commit 7f9bdc47c8318a8c6d681a3fd229bf30348ecbce
Author: Dean Troyer <email address hidden>
Date: Thu Oct 17 12:03:55 2013 -0500

    Fix typos and thinkos in docs

    Updates for the new major features and some clarification

    Partial-Bug: #1235626

    Change-Id: If2da63e62a14894e498b4163b5052d9b2b2069ed