sphinx documentation process

Motivation:

Finalize sphinx documentation practice

Contact:

Justin Deoliveira

Tracker:

http://jira.codehaus.org/browse/GEOT-3114

Tagline:

Sphinx documentation process

This page represents the current plan; for discussion please check the tracker link above.

• Description
  • Doc Organization
  • Doc Generation
  • Doc Assembly
  • Doc Continuous Build
• Status
  • Tasks
  • API Changes
  • Documentation Changes

Children:

Description {#SphinxDocumentationProcess-Description}

This proposal outlines a process for generating and managing project documentation with Sphinx.

Doc Organization {#SphinxDocumentationProcess-DocOrganization}

Documentation will be organized into three categories:

#. user guide
#. developer guide
#. web site

And reorganized in svn as follows:

trunk/
  docs/
    devel/
    user/
    web/
  modules/
  ...

Doc Generation {#SphinxDocumentationProcess-DocGeneration}

The maven build will be updated to build documentation. This will involve having maven invoke the sphinx-build utility (through ant). With this building documentation will be no different than building a regular module.

Doc Assembly {#SphinxDocumentationProcess-DocAssembly}

The assembly process that produces the bin and src artifacts will be updated. A third assembly will be added for the user guide. And potentially a fourth for the developer guide.

Doc Continuous Build {#SphinxDocumentationProcess-DocContinuousBuild}

The hudson server will be updated to build docs continuously in the same manner the rest of the code base is built when changes occur. On successful builds the latest version of the documentation will be published.

Status {#SphinxDocumentationProcess-Status}

Completed.

Voting:

• Andrea Aime +1
• Ben Caradoc-Davies +1
• Christian Mueller +1
• Ian Turton +1
• Justin Deoliveira +1
• Jody Garnett +1 (current OSGeo representative)
• Michael Bedward +1
• Simone Giannecchini +1

Tasks {#SphinxDocumentationProcess-Tasks}

 

no progress

done

impeded

lack mandate/funds/time

volunteer needed

1. Reorganize docs in svn
2. Add doc generation to maven build
3. Update assembly to produce doc artifacts
4. Add doc build to build server
5. Modify doc build to push out new website on updates
6. Port wiki content 

API Changes {#SphinxDocumentationProcess-APIChanges}

n/a

Documentation Changes {#SphinxDocumentationProcess-DocumentationChanges}

Docs currently living in web will be separated and moved into docs.