Gh pages to docs

[jodygarnett]

Setting up markdown website / documentation:

• Material for mkdocs site generation

• Q: How to do anchor for FAQ?

  Markdown supports <a name="B4"></a>. May be easier to rely on those generated based on the title text, for use in the page table-of-contents (as shown in screen snap below).

• Q: How to host javadocs?

  This is a challenge, presently they are files in gh-pages branch
  (which prevents the use of mkdocs gh-deploy that replaces entire branch
  with static content).

[dr-jts]

Good work on the PDF conversion. The Tech Specs docx file can be removed I think?

The two image directories have different names - is that intentional? Can they both be just img?

[dr-jts]

The Tech Specs docx file can be removed I think?

The two image directories have different names - is that intentional? Can they both be just img?

[dr-jts]

• Q: How to host javadocs?

Can we include javadoc building in the doc build action? So that the doc is generated, and then the javadoc is generated and pushed into a directory in the gh-pages branch. (This is what GEOS does.)

@jodygarnett

[jodygarnett]

Notes from chat:

• web/README.md has instructions for running locally
• add instructions for how to use mike to publish to gh-pages branch
• add workflow so main builds and publishes to gh-pages branch on doc change

[dr-jts]

@jodygarnett should this be pip3 ?

[micycle1]

Great initiative.

BTW best practice these days is for the action itself to build and deploy gh-pages (no need for a gh-pages branch).
(see here).

[dr-jts]

best practice these days is for the action itself to build and deploy gh-pages (no need for a gh-pages branch).

Yes, that's the goal. Once we get the doc content cleaned up, and decide how to publish the Javadoc as well.