Hi David, great progress - thanks a lot for working on this!
That said, I'm not sure we need to address the subprojects at this point. If they are linked in the overview, I guess we can just keep those links as they are (i.e., to the README on github). We only need to migrate the subproject documentation that we already have (not as README in github but as part of the website) and in those cases I don't think we need to bother moving it to the subprojects. Not saying I'm against it either - just trying to make this simpler. regards, Karl On Fri, Sep 4, 2020 at 9:18 PM David Jencks <[email protected]> wrote: > > Currently the docs for the most active subprojects aren’t in the website, > since they are READMEs in the individual subprojects. > > I did an experiment with the SCR subproject to get the same page in both the > GitHub README and the (Antora) site. > > For Antora, the sources need to be in a particular folder structure, under > modules/<module-name>/pages/, whereas for the README it should be in the root > of the subproject. Unfortunately the best way to satisfy this, with an > asciidoc include:: preprocessor instruction, is disabled by GitHub. In my > experiment, the maven build copies scr/modules/scr/pages/scr.adoc (the page > Antora works with) to src/README.adoc (visible on GitHub). > > The asciidoc (copied) README.adoc is visible at > https://github.com/djencks/felix-dev/tree/adoc-test/scr (since there’s no > README.md file GitHub shows README.adoc). > > The site with the page rendered by Antora is at > https://felix-preview.s3-us-west-2.amazonaws.com/documentation/scr/scr.html > > — > > Some choices: > > - Antora source location. It might well make more sense to put the antora > tree under src/doc/modules/scr/pages, or docs/modules/scr/pages, but I opted > in this experiment to put the pages on the shortest possible path. > > - Copying method: I used the 3rd party copy-rename-maven-plugin which hasn’t > been updated since 2014. This might be a risk. I think the antrun plugin can > be configured to do the same. > > - Multiple pages. IIUC there can only be one README, but some subprojects > have extensive documentation. I suggest that for such subprojects, we > consider moving the documentation to the subproject and having a short > non-copied README.adoc pointing to the website. > > Is migrating the docs for dead/retired subprojects a good idea? > > David Jencks -- Karl Pauls [email protected]
