OOPS wrong list, sorry, David Jencks
> On Jul 21, 2021, at 9:37 AM, David Jencks <david.a.jen...@gmail.com> 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 > >
