Automatic documentation deployment

[alexfleury-sb]

Automatic documentation deployment

Currently, updating the Tangelo documentation involves significant manual work. We would like to have an automatic deployment workflow, similar to what we have set up in the Tangelo-Examples repo.

What problem does this feature request help you overcome?
As of now, regenerating or updating the documentation requires performing the steps outlined in dev_tools/build_sphinx_docs.sh locally, and then uploading the files to an AWS bucket. It's cumbersome and manual, and sometimes it may not be updated right away.

Describe the solution you'd like
We would like an automatic workflow (similar to the one in the Tangelo-Examples repo, see files below) to compile and upload the documentation using GitHub Pages every time the main branch is updated, to guarantee that our documentation is always reliable !

• The documentation left behind by past versions of ourselves should be helpful here: https://github.com/goodchemistryco/Tangelo-Examples/blob/main/dev_tools/generate_documentation.rst
• An "automated workflow" file we should add to the repo is available here
• There are also other online resources that may be relevant.

The source files would reside in a gh-pages branch, and the website could be accessed via a GitHub Pages address https://goodchemistryco.github.io/Tangelo. After that, we would only need to point http://tangelo-docs.goodchemistry.com/ to the corresponding GitHub page. (this address will be changed to a SandboxAQ address later, don't worry about it 😄 )

[king-p3nguin]

Hi, I am working on this issue and would like to know whether you prefer generating documentation using Quarto or Sphinx.

[alexfleury-sb]

Hello @king-p3nguin, thank you! From what I have seen Quarto is designed to render notebooks, so one has to use https://github.com/machow/quartodoc to render API documentation (as discussed in quarto-dev/quarto-cli#2111 - I just learnt about this). I am personally leaning toward Quartodoc (vs Sphinx), but I don't have a strong opinion on this. If you are used to Sphinx, we would be fine with a solution using it.

[ValentinS4t1qbit]

Thanks for asking @king-p3nguin 👑 🐧 !

I'm fine with either as well. I think right now having an automated solution is more important. Here are some thoughts:

What I personally like about Sphinx

I know that Sphinx could also support performance extensions to our code base in C/C++ or Julia down the line. Sphinx has been around a while and I also know that the website could be customized with css etc, so that's a plus if we want to make the website pretty. Our existing solution relies on Sphinx, so some of it can be reused to solve this Github issue

Quartodoc

I must say I am pretty curious ! It seems restricted to Python but I don't think that should be a deal breaker. We may figure ways to add more to it later, and can ask the project maintainer questions or maybe suggest additional features. I am happy if we go for this and learn about this solution as well !

@king-p3nguin Is it possible for you to generate a "browsable" preview of the solution you will shoot for ? (either a link where website is hosted, or I think a zip folder containing the html files would work). Let us know if there's anything we can do to help, in case we need to modify the settings of this Github repo or something to facilitate completion 👍

When it comes to visuals, honestly: if it looks like the docs are browsable and well-rendered, and the Tangelo logo (tangelo_logo_gradient or tangelo_logo_white in https://github.com/goodchemistryco/Tangelo/tree/main/docs/source/_static/img) the top bar, then it's a win ! Then we'll try to tweak things ourselves afterwards because people are picky but it would be unfair to ask you to change things until we are happy ;)

[king-p3nguin]

@ValentinS4t1qbit @alexfleury-sb Thank you for the detailed comment!

I have experience building Sphinx documents for my project, so I will focus on automatic documentation deployment using Sphinx. I will try it on my fork and make a PR.

[Roshan-Thomas]

Hi! Is this issue still open to be worked on by others, or is it assigned to one particular person?

[ValentinS4t1qbit]

@Roshan-Thomas I think it is indeed a bit too late, it seems like we may already have a working solution that will come live once we update main :)

[ValentinS4t1qbit]

@king-p3nguin Sorry, I have been busy ! Thank you so much for your work, I may have a question or two for you later on :)