[
https://issues.apache.org/jira/browse/COUCHDB-1787?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13648367#comment-13648367
]
Dave Cottlehuber commented on COUCHDB-1787:
-------------------------------------------
Danish, not quite. In the couchdb source
https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/doc/src
are the .rst format files, and also a conf.py file that uses the sphinx project
http://sphinx.pocoo.org/ to build our documentation. You should read up on
sphinx to have a better idea of how this works.
Once we enter the release process
http://wiki.apache.org/couchdb/Release_Procedure#Preparing_the_Docs , we
compile manually lists of changes from git commits, documentation, JIRA
tickets, and put them into CHANGES, NEWS, and also into blog posts. This is all
manual today.
If we can get this down to a single `make changes` target in our makefile, that
calls an extension of python sphinx to extract the information, this whole
process becomes much simpler, and more reliable. It also forces us to get
better at using docs and commits as a way of tracking these changes.
We'd like to use the .rst tags that Alex mentioned as a way of extracting all
significant changes for this current version, and hand that back to the person
doing the release to amend as needed. Potentially that amended file can go back
into the source tree and then regenerate the 3 output formats - HTML for
blog/website update, plain text for CHANGES/NEWS, and wiki content a la
http://wiki.apache.org/couchdb/Release_Procedure#Making_the_Release
There's possibly 3 parts here:
- a nice clean python module or script that extends sphinx to extract a list of
..version* tags and builds a suitable list of changes, ordered by version.
- a separate module or script that takes a manually tweaked .rst file and spits
out HTML for the blog/website, plain text for CHANGES/NEWS, and if we still do
that in future, wiki content
- work on hooking all of this into GNU Makefile which is how we build our
releases:
https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=Makefile.am;hb=HEAD
A reminder for your submission that it's due Friday 5th May, and that you need
to follow the guidelines for GSoC. A simple "I want to do this" will be
unlikely to get in ;-)
> Automate release process documentation
> --------------------------------------
>
> Key: COUCHDB-1787
> URL: https://issues.apache.org/jira/browse/COUCHDB-1787
> Project: CouchDB
> Issue Type: Improvement
> Components: Build System, Documentation
> Reporter: Dave Cottlehuber
> Labels: gsoc2013, sphinx
>
> The release process today contains a large number of manual transformation
> steps.
> Fixing this will make the release process significantly easier for release
> managers, as well as less error-prone.
> Ideally the output formats (NEWS, CHANGES in source tree, and HTML snippets
> for http://couchdb.org/ website and http://blogs.apache.org/couchdb ) can be
> auto-generated from either the .rst files in share/doc/src using sphinx's
> .versionaddded/changed tags, or potentially from commit messages if this is
> appropriate.
> CouchDB documentation is generated today from restructured text using python
> code, and rolled into the release documentation during `make distcheck`.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
