On Oct 30, 2012, at 11:39 AM, Aristedes Maniatis <[email protected]> wrote:
> On 29/10/12 7:48pm, Andrus Adamchik wrote: > >> Yes, but is this even an issue? Most docs should not be published on each >> code commit, and should be deferred till we make an official release. Our >> releases are fairly formalized events with a documented scenario that a >> release manager follows. One of the steps in this scenario can be doc >> publishing. > > Personally I rather see the documents as living things where fixes and > improvements are continuously rolled out. Waiting 18 months to release doc > fixes or improvements doesn't seem helpful. We are talking about 2 complimentary scenarios here: 1. the docs (including Javadocs) that describe the code that is yet unreleased. 2. the docs that describe things already released and available. I'd say we should wait 18 months (or whatever it takes to release the underlying code) with #1. And you are absolutely right about #2. So I guess we need publishing scenarios for both cases and then see how that maps to CI. I will try to find time to check the Perl stuff… Andrus On Oct 30, 2012, at 11:39 AM, Aristedes Maniatis <[email protected]> wrote: > On 29/10/12 7:48pm, Andrus Adamchik wrote: > >> Yes, but is this even an issue? Most docs should not be published on each >> code commit, and should be deferred till we make an official release. Our >> releases are fairly formalized events with a documented scenario that a >> release manager follows. One of the steps in this scenario can be doc >> publishing. > > Personally I rather see the documents as living things where fixes and > improvements are continuously rolled out. Waiting 18 months to release doc > fixes or improvements doesn't seem helpful. > > > I've now imported doc12/doc20/doc30 into our new CMS, ripped out the headers > and footers in each file, and converted the Title into the same format as the > other pages. I left out /doc for now until we understand whether we'll be > able to get our docbook up to speed for 3.1. > > http://cayenne.staging.apache.org/doc30/overview.html > > > The problem here is some Perl you might be able to help with. Look at > path.pm, we probably need to add a line like: > > [qr!\.html$!, single_narrative => { template => "single_narrative.html" > }], > > and then edit view.pm where you see > > sub single_narrative { > > Ideally we'd disable Django processing ( > http://search.cpan.org/~maluku/Dotiac-0.8/lib/Dotiac/DTL.pm ) but we still > want it to parse the "Title" tag in the top of the page. I can't find which > bit of code does that. > > > > Next, for the docs inside the /api/ folder, we want to stop it adding any > templating at all. I guess that's another path.pm entry. > > > Some of this will be trial and error I think.... > > > I'm chatting to a Lucene guy about how they did their news on their home > page. http://lucenenet.apache.org/ Seems simple enough but it means we'd move > to the Apache Blog tool for all our news entries. It is pretty ugly: > > https://blogs.apache.org/lucenenet/entry/lucene_net_3_0_3 > > But it does allow comments which is nice. > > > Ari > > > > > -- > --------------------------> > Aristedes Maniatis > GPG fingerprint CBFB 84B4 738D 4E87 5E5C 5EFA EF6A 7D2E 3E49 102A >
