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
