Hi David,
the directory path is not nice and deep, but I don't mind that much.
I didn't want to rehash a discussion about markdown vs asciidoc in
general - asciidoc for our website is totally fine. There is not much
happening on that front anyway.
As I said if everyone is fine with converting the sub project docs
stored next to the code from markdown to asciidoc as well, so be it.
So we should really hear from others
Regards
Carsten
Am 30.07.2021 um 08:42 schrieb David Jencks:
inline...
On Jul 29, 2021, at 9:28 PM, Carsten Ziegeler <cziege...@apache.org> wrote:
I like the approach in general, the location of the adoc file within the scr
tree is a little bit awkward, but not a showstopper.
To me Antora directory structure is a bit like maven project layout, once you
get used to it anything else seems odd.
We could shorten the path slightly to
<subproject>/docs/modules/<subproject>/pages/<doc-page>.adoc, making each
subproject an Antora “module”.
I think it’s a good idea to separate the docs under “docs” although Antora would be just
as happy with <subproject>/modules>/…
The directory name “modules” doesn’t immediately imply “documentation” to me,
and this shortening would put the required antora.yml next to e.g. the pom.xml.
What I personally don't like is that these files need to be written in asciidoc
and not gh markdown. But if everyone else is fine with that, I can probably
adjust.
It might have been more appropriate to bring this up when I proposed using
Antora.
I’m curious what you prefer about markdown. I would not participate in a
documentation project using markdown rather than AsciiDoc: I find it ugly and
limited.
David Jencks
Regards
Carsten
Am 29.07.2021 um 02:31 schrieb David Jencks:
I’ve set up a somewhat usable preview workflow and a preview for scr for what
I’d like for the subproject docs.
Take a look at https://felix.staged.apache.org/. Scr is now in the nav under
subprojects and linked from the table of subprojects.
The minimal README.adoc is visible at
https://github.com/djencks/felix-dev/tree/adoc-preview/scr. Note that here
GitHub is rendering AsciiDoc. The source scr website content is at
https://github.com/djencks/felix-dev/blob/adoc-preview/scr/docs/modules/ROOT/pages/subprojects/scr.adoc
I’d suggest doing this transformation for all the subprojects currently relying
on READMEs and moving the docs for the other subprojects from the
felix-antora-site repo to appropriate places in felix-dev.
David Jencks
On Jul 27, 2021, at 12:17 PM, David Jencks <david.a.jen...@gmail.com> wrote:
The new version of that page,
https://felix.staged.apache.org/documentation/subprojects.html, still has links
to the GitHub README. If we stick with this (my 3rd option) we should at least
also have links in the nav.
I suspect that it’s not clear how my preferred solution would work or look.
I’ll see about setting up a preview for scr, since I already translated the
README to .adoc.
In any case I’d suggest translating all the READMEs to AsciiDoc so all the
documentation is in the same language. GitHub renders AsciiDoc for READMEs
automatically.
David Jencks
On Jul 27, 2021, at 2:05 AM, Carsten Ziegeler <cziege...@apache.org> wrote:
Am 27.07.2021 um 10:59 schrieb Bertrand Delacretaz:
On Tue, Jul 27, 2021 at 10:50 AM Carsten Ziegeler <cziege...@apache.org> wrote:
...I prefer having the docs of a subproject directly within git as this
makes updates that involve code and docs much easier (a single PR)...
I also like that option as long as all modules are discoverable from
the main website.
For Sling and its more than 300 modules we have
https://sling.apache.org/repolist.html which lists all modules on a
single page.
Good point, we have this at
https://felix.apache.org/documentation/subprojects.html , the links currently
either point to a readme in git or a page on the website.
Regards
Carsten
--
Carsten Ziegeler
Adobe Research Switzerland
cziege...@apache.org
--
--
Carsten Ziegeler
Adobe Research Switzerland
cziege...@apache.org
--
--
Carsten Ziegeler
Adobe Research Switzerland
cziege...@apache.org
