incubator-cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Nalley <da...@gnsa.us>
Subject Re: Revived - Re: [WEBSITE][DOCS] Publican-based docs publishing?
Date Thu, 20 Sep 2012 13:39:52 GMT
On Thu, Sep 20, 2012 at 4:52 AM, Noah Slater <nslater@tumbolia.org> wrote:
> We're using svnpubsub, right? Can Publican be used in such a way as to
> generate the output formats in an SVN repository? If so, we should be able
> to commit the files each time, and use our regular website. No need for
> infra to do anything.

Yes we are using svnpubsub and that should work just fine.

>
> As David suggested in the original thread, you could put Publican under one
> dir, and you could put the API reference under another dir. That leaves our
> homepage, etc, as a "marketing site" that draws people into the project.
>
> On Thu, Sep 20, 2012 at 1:05 AM, Jessica Tomechak <
> jessica.tomechak@gmail.com> wrote:
>
>> +1 for Publican website (you've convinced me!)
>>
>> Now, who will set up such a website? Do we need to file a ticket with the
>> infrastructure team? Can it be done in time for 4.0 release?
>>
>> And can we also place any other HTML there, such as our 400+ pages of API
>> Reference which isn't generated by Publican?
>>
>> Jessica T.
>> CloudStack Tech Pubs
>>
>>
>> >
>> > -----Original Message-----
>> > From: Sebastien Goasguen [mailto:runseb@gmail.com]
>> > Sent: Thursday, September 06, 2012 2:44 AM
>> > To: cloudstack-dev@incubator.apache.org
>> > Subject: Re: Revived - Re: [WEBSITE][DOCS] Publican-based docs
>> publishing?
>> >
>> > +1 for Publican based docs website
>> >
>> >
>> > On Sep 5, 2012, at 5:56 PM, Joe Brockmeier <jzb@zonker.net> wrote:
>> >
>> > > Hi all,
>> > >
>> > > Noticed that docs.cloudstack.org is down at the moment, which reminded
>> > > me that we haven't come to a conclusion on this topic.
>> > >
>> > > The options before us are:
>> > >
>> > > - A Publican-generated site from the CloudStack documentation.
>> > > - A docs.cloudstack.org site powered by MindTouch wiki.
>> > >
>> > > The previous discussion is easily skimmable here:
>> > >
>> > > http://markmail.org/thread/j57gbt5g4vtbk2iw
>> > >
>> > > My opinion is that we should go with the Publican-generated site. It's
>> > > much less maintenance and can easily be hosted on Apache
>> infrastructure.
>> > > But, please do look over the earlier thread and if you have an
>> > > interest in participating in CloudStack docs - please do speak up with
>> > > a preference.
>> > >
>> > > Thanks,
>> > >
>> > > Joe
>> > >
>> > > On Thu, Aug 16, 2012, at 02:46 PM, David Nalley wrote:
>> > >> 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
>> > >
>> > > --
>> > > Joe Brockmeier
>> > > jzb@zonker.net
>> > > Twitter: @jzb
>> > > http://www.dissociatedpress.net/
>> >
>> >
>>
>
>
>
> --
> NS

Mime
View raw message