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
cziege...@apache.org
