Create a website with documentation

[Chad-Peterson]

We need to create a website with documentation such as an API reference guide. We will likely use Sphinx and GitHub Pages.

[Chad-Peterson]

Hi @ruansava and @satyartpeddada, this is the issue I was talking about for planning how to externally document our work. Please feel free to share thoughts below. We will talk tomorrow, but here is the link to GitHub Pages: https://pages.github.com/

It looks really simple to setup a webpage with Pages if your repo is already on GitHub since the website is hosted directly from your GitHub repo. You just have to edit and push your changes and the website will update automatically.

Note that GitHub Pages is available for public repositories for free. It requires a professional license for private repos. We plan to make this repo public in the somewhat near term (https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site). My thoughts are to focus on getting some simple features to work on SPI2py, then in a little while making it public and catching up on documentation.

I'm open to other ideas, Pages just seems so easy/streamlined to use and it's free.

[ruansava]

Hi everyone!
Thinking in future documentation, we could use something like that:

• For managing: https://www.sphinx-doc.org/en/master/
• For publishing on the web: https://readthedocs.org/

Examples of this type of documentation:

• FEniCS project: https://docs.fenicsproject.org/dolfinx/main/python/
• Devito project: https://www.devitoproject.org/devito/index.html
  I don't have experience with any of them but we can learn together.

For benchmarks and tutorials, we can use the following, supported by a GitHub repository:

• Jupyter Notebooks: https://jupyter.org/
• Example from Firedrake : https://nbviewer.org/github/firedrakeproject/firedrake/blob/master/docs/notebooks/01-spd-helmholtz.ipynb

I had some contact with Jupiter using Fenics and Devito. There were some free Devito samples in Azure but unfortunately, they are no longer there. This shows the potential to run in the cloud medium-scale models (for large-scale ones, no GUI is better) without sophisticated configurations.

On the other hand, this is a book with recommendations for programming in Python (the website uses Sphinx):

• OOP in Python for Mathematicians by David Ham: https://object-oriented-python.githu)b.io/