cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Nalley <da...@gnsa.us>
Subject [WEBSITE][DOCS] Publican-based docs publishing?
Date Thu, 16 Aug 2012 19:46:12 GMT
Hi folks,

Wanted to toss this out there and get some reaction.

We use Publican to transform our documentation XML into consumable
formats like HTML, EPUB, PDF, etc.
Publican has a number of other functions, and one of those is
publishing a documentation website. I've participated in this with
other projects, and it seems to be relatively easy. (it's literally
two commands to build and publish a document) So I started playing
with this today - and you can take a look at my VERY UNPOLISHED
results. I only spent a few hours on this today, so there is still
plenty that needs to happen for this to look presentable, but please
have a look.

http://people.apache.org/~ke4qqq/docs

A couple of things I'll point out. The interface is completely
localized in scores of languages - and it will automagically load to
match your browsers locale provided there are docs in that language.
To date though we only have zh_CN, and only for a single document. You
can also manually set your language.
The TOC on the left is divided by 'product' [1], then by version [2],
and then document. I will note that you are presented with all of the
formats that the document was built for (so you'll see HTML,
HTML-Single, PDF and EPUB and the latter two options are download
links for the docs.) And that permits you to load your content pretty
easily.


[1] I'd imagine we'd generally only have a single product - Apache
CloudStack, but perhaps there will be others, like Apache CloudStack
Contributor Documentation which is separate from user documentation
[2] Selecting a version shows you all available documents for that
version in your language of choice

What do folks think of presenting our 'official documentation' in this
manner? Is it something worth pursuing? I was thinking having this be
a docs/ subdirectory on the project site (e.g.
incubator.apache.org/cloudstack/docs, is there a better place for it?

Thoughts, comments, or flames are welcome.

--David

Mime
View raw message