OOPS wrong list, sorry,
David Jencks
> On Jul 21, 2021, at 9:37 AM, David Jencks wrote:
>
> 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 subproject git repo. 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?
>
> David Jencks
>
>
