On 29/10/12 5:54pm, Andrus Adamchik wrote:
Awesome!
1c Fix or remove news: I asked oninfra and was pointed to some similar solutions
Unless we have a plan for this, I suggest moving the most recent blog entry
announcements to Apache CMS pages, and manually filling the summary section on
the home page. We'll revisit it later.
1d Breadcrumb doesn't work:we have code for this, but do we even need it?
Yeah, it was useful, but not that useful to delay migration.
I just removed it.
I don't know where we are with 2a. Is this mostly done? Somewhat done?
The new docs are for 3.1 and 3.2 only. (Older releases will keep using
SVN-checked wikidocs of course)
The docs are not finished (we have 100% of tutorials, ~60-70% of Cayenne Guide,
1% of Modeler Guide). But I still suggest publishing what we have in docbook
and do not preserve wikidocs for 3.1 (and 3.2). The docbook project is a
complete rewrite, rather then porting of the old docs. So it doesn't have any
legacy assumptions and attempts to present a consistent picture of the
framework the way I see it now (as opposed to the way I saw it ca 2004).
Conversely wikidocs doesn't have anything on 3.1 DI, and will confuse anybody
trying to get started with Cayenne 3.1
OK, then we just have to get it finished before we release 3.1. Until then it
can serve as partial documentation with an early focus on the new features.
Sounds fair?
Actually I found our docbook output:
http://ci.apache.org/projects/cayenne/docbook/
Another issue with doc publishing - should we be tying doc publishing to CI?
All doc changes can be roughly split into two categories - those catching up
with an existing release and those corresponding to the yet unreleased code.
Especially the Javadocs will mostly fall in the second category… So maybe we do
docbook+javadoc publishing manually by checking in the built files to the site
SVN folder? This way we can do both - fix doc bugs between releases and time
publishing with a given release.
I think that tying it into CI is much simpler. Otherwise it relies on people
remembering to commit and publish. And the buildbot documentation build doesn't
fail in odd ways like the big Jenkins run against different databases.
But I agree that we need a way to easily branch the docs and publish them in a
sane way. Let me get some more answers from infra about the staging/publishing
process when we want to bypass svn committing for the output.
In theory, docbook is just an alternative to textile or markdown. But I don't
think that would be easy to tie into Perl somehow...
Thoughts?
I've never written Perl, so much of the scripting is a bit foreign to me.
I have some Perl skills (I can *write* in Perl, but often can't read other's code :) Perl
is "write-only" after all :)). Let me know if you need help with Perl scripting.
Great. To me Perl looks like one multiline regular expression.
Ari
--
-------------------------->
Aristedes Maniatis
GPG fingerprint CBFB 84B4 738D 4E87 5E5C 5EFA EF6A 7D2E 3E49 102A
