Add docs site, analysis pages and CI workflows

[Atilaac]

Add a complete MkDocs-based documentation site and CI.
Includes mkdocs.yml, many new docs (analysis pages for RDF, Qn, bond angles, rings, cavities, CTE, API reference, workflows, index, styles and JS), docs assets (logo.svg), a generate_logo.py helper, and two GitHub Actions: test_docs.yml to validate builds on PRs and deploy_docs.yml to publish via mkdocs gh-deploy on push to main/master.
These changes enable automated doc validation and deployment.

I believe you (@ltalirz) should activate GitHub Pages for this to work.

We can use these docs as a starting point and extend them.

[github-actions]

[Atilaac]

the doc website look like this.

[ltalirz]

Hi @Atilaac , this looks great, thanks a lot for working on this!

Github pages

As we discussed previously, we can build the documentation locally (and test building it on CI) until we go public; then we can publish it to Github pages.

Framework

Once question from my side concerns the documentation framework to use. I personally like mkdocs + material + mkdocs-jupyter for the jupyter notebooks, I just want to make sure @jan-janssen is also fine with this, since we discussed other frameworks before (jupyter book?).

Organization

One question pops into my mind here: how do we distribute documentation between the MarkDown files and the Jupyter notebooks? It is worth thinking about this now, since any significant duplication will come back and bite us later.

I actually like that our current notebooks are descriptive and somewhat self-contained, and I think when making changes to a workflow, it is easier to remember to change the notebook (which one anyhow modifies) rather than change some related place in the documentation. There are frameworks like this one for how to think about structuring documentation. Our current notebooks are "how-to guides" - they address a real-world goal from start to finish.

Based on these considerations, I propose the following adaptation of your structure

• "Home" or "Introduction"
  • "Key Features": I'd include your "typical workflow figure" below the feature list
  • "Installation" (could also be a separate top-level section, but we can keep it here)
  • Authors
  • License
• "Quick Start" or "Tutorial": We use this to explain common concepts that people may not be familiar with and that we don't want to write in every notebook, e.g. about how our functions typically work; how to use the executor concept etc.
• "How-To Guides"
  • subsections will mostly be the notebooks, rendered via HTML
• "Theory" or "Topics" : here goes your MarkDown text, but probably with less code examples, rather link to the respective notebook. Also: For explaining input/output parameters of functions, I suggest to link directly to the documentation of the respective function in the automatically generated API docs (in sphinx there is also a way to show it inline, not sure whether this is possible in mkdocs) - if the information you would like users to see is not there already, we should move that information to the code.
  • "Structure generation"
  • "Interatomic Potentials"
  • "Simulation Workflows"
  • "Structural Analysis"
• "Developers" or "Architecture": developer-focused stuff
  • your "package organization" might go here
• API Reference

Curious to hear your thoughts!

[jan-janssen]

Once question from my side concerns the documentation framework to use. I personally like mkdocs + material + mkdocs-jupyter for the jupyter notebooks, I just want to make sure @jan-janssen is also fine with this, since we discussed other frameworks before (jupyter book?).

Jupyter book was just a suggestion, mkdocs looks nicer, so I am fine with both. For me the important aspect is that we have the capability to test the code that is shown in the examples to guarantee that they are consistent with the latest version of our software.

[ltalirz]

Navigation

P.S. I notice that in your screenshot the left column below "HOME" is completely empty, which seems like a waste of space.
I don't know what the suggested use of this column is for this layout, where you have navigation info already in the top bar and on the right, but maybe there is some?

https://hypercoast.org e.g. has no top bar and looks clean to me, but I'm not strongly in favor of one of the other layout; just that we make sensible use of the space available

[Atilaac]

I believe there are no issues into having both, a full documentation of usage of each function of the code (which I usually need and like), and having fully testable and working jupyter-notebooks as Hand-on materials or tutorials that shows some real life examples of typical glass simulations. Regarding the layout I will try to mimic the given example you shared to make use of that empty space.

[ltalirz]

Thanks a lot @Atilaac - my first comment: before merging this please drop the built site from the PR again as this blows up the branch enormously.

As long as we don't serve the site via github actions we don't need to track it in git at all. Once we do, people typically do this in a separate branch like gh-pages (tracking a build artifact like the website is not really what git was made for, but this is how github pages works and so using a separate branch at least allows you to keep this separate from the source).

[ltalirz]

@Atilaac in my commits I just took the liberty to

• delete the site/ directory
• switch from the branch-based github pages build to an artifact-based build (meaning we no longer need to track the site in git at all)

Once we make the package public, we can

Go to Settings → Pages → Source → "GitHub Actions".

[ltalirz]

Thanks for adapting the layout (which I find much more intuitive) and the documentation structure.

I don't have the time to review each page of the documentation but I think this is a very good starting point and we can go ahead and merge it.