MJ-28 ⁃ Create micronaut-style docs

[stainlessbot]

Start writing some actual documentation for the project (beyond just what is in the README). These docs should follow a similar theme to the docs that Micronaut uses for their configurations. Try using the same documentation library (adoc?).

┆Reporter: Joshua Carter ┆Issue Type: Story ┆Priority: Low ┆Status: Resolved ┆Fix Versions: v0.2.4 ┆Issue Number: MJ-28 ┆Epic: Documentation

[stainlessbot]

➤ Joshua Carter commented:

From what I can tell, the micronaut-docs project is really just intended for internal use (i.e. the micronaut configurations and modules created by the micronaut team).

It is open source, so we could copy the styles and docs generation if we wanted too... but it doesn't seem that kosher; instead of copying Micronaut's styles, we should use our own (of probably to start with, a default theme for whatever documentation library we use).

I can't find any other micronaut configurations that have separate documentation that isn't from the micronaut team. Ascii Doctor is really a text pre-processor as opposed to a documentation library. If it has features that we want, we can use it, but whatever example we come up will have to include more than just ascii doctor.

My inclination would be to go with a solution that we used for an internal groovy library, which was to use the documentation library docusaurus to create a static docs website, which can be hosted using GitHub pages.

[stainlessbot]

➤ Joshua Carter commented:

Docusaurus has instructions for how to publish to GitHub pages: https://docusaurus.io/docs/en/publishing#using-github-pages

There are other ways to do it, but the advantages of this method is that the build artifacts for the docs website don't have to be versioned on master, they go on a separate gh-pages branch, which can be committed to after a release to the master branch.

The above link also contains documentation for how to use Travis CI. We will want to do things a bit differently than they are doing it there, but essentially, if the travis bash script is run, if the branch is master, in addition to assembling the artifact, also publish the documentation (alternatively, we may actually want to publish the documentation along with the publish task on the version tag branch, so that all the publishing tasks can be done in one tavis execution, that is probably better).

[stainlessbot]

➤ Joshua Carter commented:

Let's try and use Docusaurus v2, even though it appears to be still in alpha: https://v2.docusaurus.io/docs/deployment#deploying-to-github-pages https://v2.docusaurus.io/docs/migrating-from-v1-to-v2

[stainlessbot]

➤ Joshua Carter commented:

Going to try out the no-style theme in order to make adding custom styles a bit easier: https://docusaurus-template-no-style.netlify.com/

[stainlessbot]

➤ Joshua Carter commented:

What I really wanted was to be able to create some single page docs (like Micronaut does). Docusaurus doesn't really support that, and I couldn't find any other documentation generators that do either.

So I've decided to go back to the idea of using micronaut-docs. After playing around with it for a few hours, I've figured out that it is actually highly customizable (using an HTML templating system) so that we should be able to use our own styles and such. What it doesn't have is documentation of any sort what-so-ever.

[stainlessbot]

➤ Joshua Carter commented:

The work on the project needed for this is complete and ready to be released. However; after the release, additional work will need to be done on the gh-pages branch.

[JoshuaCWebDeveloper]

Docs are up at: https://stainlessai.github.io/micronaut-jupyter