You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@felix.apache.org by David Jencks <da...@gmail.com> on 2021/07/26 19:49:40 UTC
Putting subproject docs in the code repos
The CMS website and the Antora website currently have the docs source far from the code. As a result several subprojects (SCR, Atomos at least) have put their documentation in a README in the same git repo as the code. This results in these subproject documentation appearing really different from other subprojects docs and lacking the overall navigation facilities from the site. Currently the Antora based website doesn’t attempt to include this documentation.
With Antora this is not necessary: Antora can extract documentation source from any number of git repos and assemble it all seamlessly. I think it would be a good idea to set this up. In general Antora requires sources in each git repo to be in a specific directory structure, for the current felix site `…/modules/ROOT/pages/*.adoc`.
There are several choices for how to do this:
- Move the README contents to a concrete .adoc page in the above structure and have the README mostly point to the website. This allows use of the full power of Asciidoc on the pages, rather than the quite constricted subset available from the GitHub asciidoc renderer (or the GitHub markdown renderer). I think this is the best choice.
- Symlink from the above structure location to the README (which will need to be translated to Asciidoc, which will still be rendered by GitHub). Symlink support was recently added to Antora but I haven’t tried it in this scenario. This would give the same content at GitHub (in roughly its current format) and in the website(integrated, with nav, header, footer, etc), but would limit subproject documentation to a single page and inhibit links to other website pages, among other problems.
- Add (external) links in the nav to the READMEs on GitHub. In this case there will be no version of the documentation integrated into the website.
Thoughts?
Some other current and future possibilities with Antora:
- It’s easy to have many versions of documentation for each subproject. However, I doubt the effort to maintain multiple documentation versions is reasonable for the Felix community.
- Most likely soon it will be plausible to include javadoc as site pages with navigation, ability to link to javadoc pages, etc. AFAICT the limited apidocs currently in the site are not linked to in any way.
David Jencks
Re: Putting subproject docs in the code repos -- sample preview
available
Posted by Carsten Ziegeler <cz...@apache.org>.
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 <cz...@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 <da...@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 <cz...@apache.org> wrote:
>>>>>
>>>>>
>>>>>
>>>>> Am 27.07.2021 um 10:59 schrieb Bertrand Delacretaz:
>>>>>> On Tue, Jul 27, 2021 at 10:50 AM Carsten Ziegeler <cz...@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
>>>>> cziegeler@apache.org
>>>>
>>
>> --
>> --
>> Carsten Ziegeler
>> Adobe Research Switzerland
>> cziegeler@apache.org
>
--
--
Carsten Ziegeler
Adobe Research Switzerland
cziegeler@apache.org
Re: Putting subproject docs in the code repos -- sample preview
available
Posted by David Jencks <da...@gmail.com>.
inline...
> On Jul 29, 2021, at 9:28 PM, Carsten Ziegeler <cz...@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 <da...@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 <cz...@apache.org> wrote:
>>>>
>>>>
>>>>
>>>> Am 27.07.2021 um 10:59 schrieb Bertrand Delacretaz:
>>>>> On Tue, Jul 27, 2021 at 10:50 AM Carsten Ziegeler <cz...@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
>>>> cziegeler@apache.org
>>>
>
> --
> --
> Carsten Ziegeler
> Adobe Research Switzerland
> cziegeler@apache.org
Re: Putting subproject docs in the code repos -- sample preview
available
Posted by Carsten Ziegeler <cz...@apache.org>.
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.
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.
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 <da...@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 <cz...@apache.org> wrote:
>>>
>>>
>>>
>>> Am 27.07.2021 um 10:59 schrieb Bertrand Delacretaz:
>>>> On Tue, Jul 27, 2021 at 10:50 AM Carsten Ziegeler <cz...@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
>>> cziegeler@apache.org
>>
>
--
--
Carsten Ziegeler
Adobe Research Switzerland
cziegeler@apache.org
Re: Putting subproject docs in the code repos -- sample preview
available
Posted by David Jencks <da...@gmail.com>.
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 <da...@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 <cz...@apache.org> wrote:
>>
>>
>>
>> Am 27.07.2021 um 10:59 schrieb Bertrand Delacretaz:
>>> On Tue, Jul 27, 2021 at 10:50 AM Carsten Ziegeler <cz...@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
>> cziegeler@apache.org
>
Re: Putting subproject docs in the code repos
Posted by David Jencks <da...@gmail.com>.
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 <cz...@apache.org> wrote:
>
>
>
> Am 27.07.2021 um 10:59 schrieb Bertrand Delacretaz:
>> On Tue, Jul 27, 2021 at 10:50 AM Carsten Ziegeler <cz...@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
> cziegeler@apache.org
Re: Putting subproject docs in the code repos
Posted by Carsten Ziegeler <cz...@apache.org>.
Am 27.07.2021 um 10:59 schrieb Bertrand Delacretaz:
> On Tue, Jul 27, 2021 at 10:50 AM Carsten Ziegeler <cz...@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
cziegeler@apache.org
Re: Putting subproject docs in the code repos
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Tue, Jul 27, 2021 at 10:50 AM Carsten Ziegeler <cz...@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.
-Bertrnad
Re: Putting subproject docs in the code repos
Posted by Carsten Ziegeler <cz...@apache.org>.
I think this is a tough one. It seems today people using github expect
the documentation to be part of the git repo in the form of a readme. It
also seems that having the docs side by side with the code helps in
keeping them in sync.
On the other hand having the docs as part of our website adds all the
helpful navigation and links section to it and allows for branding.
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). So I
would prefer a solution that allows this.
Regards
Carsten
Am 26.07.2021 um 21:49 schrieb David Jencks:
> The CMS website and the Antora website currently have the docs source far from the code. As a result several subprojects (SCR, Atomos at least) have put their documentation in a README in the same git repo as the code. This results in these subproject documentation appearing really different from other subprojects docs and lacking the overall navigation facilities from the site. Currently the Antora based website doesn’t attempt to include this documentation.
>
> With Antora this is not necessary: Antora can extract documentation source from any number of git repos and assemble it all seamlessly. I think it would be a good idea to set this up. In general Antora requires sources in each git repo to be in a specific directory structure, for the current felix site `…/modules/ROOT/pages/*.adoc`.
>
> There are several choices for how to do this:
>
> - Move the README contents to a concrete .adoc page in the above structure and have the README mostly point to the website. This allows use of the full power of Asciidoc on the pages, rather than the quite constricted subset available from the GitHub asciidoc renderer (or the GitHub markdown renderer). I think this is the best choice.
>
> - Symlink from the above structure location to the README (which will need to be translated to Asciidoc, which will still be rendered by GitHub). Symlink support was recently added to Antora but I haven’t tried it in this scenario. This would give the same content at GitHub (in roughly its current format) and in the website(integrated, with nav, header, footer, etc), but would limit subproject documentation to a single page and inhibit links to other website pages, among other problems.
>
> - Add (external) links in the nav to the READMEs on GitHub. In this case there will be no version of the documentation integrated into the website.
>
> Thoughts?
>
> Some other current and future possibilities with Antora:
>
> - It’s easy to have many versions of documentation for each subproject. However, I doubt the effort to maintain multiple documentation versions is reasonable for the Felix community.
> - Most likely soon it will be plausible to include javadoc as site pages with navigation, ability to link to javadoc pages, etc. AFAICT the limited apidocs currently in the site are not linked to in any way.
>
> David Jencks
>
--
--
Carsten Ziegeler
Adobe Research Switzerland
cziegeler@apache.org