Docs (readthedocs) ?

[stuaxo]

Planar had some nice HTML docs https://pythonhosted.org/planar/transforms.html

I'm not sure how the above docs are generated, if they are something standard it may be worth moving docs to readthedocs.

It would be good to get these for Affine, it may be a matter of contacting Casey, I know a number of years ago he was pretty keen for someone to pick up Planar, so don't imagine this would be a problem.

[Rotzbua]

Created a PR to build a single site documentation.

Result looks like this: https://rotzbua.github.io/affine/

[stuaxo]

From a quick scan that looks nice :)

Where would these be hosted, on github pages ?

[Rotzbua]

Where would these be hosted, on github pages ?

Right. Hosted on github pages. The actions build the html and uploads the documentation html artifact to pages.

From a quick scan that looks nice :)

Thanks :) I know that it is just an 80% solution e.g. versioned documentation is missing but I think it is the simplest solution without additional external services at the moment.

[stuaxo]

Having messed with docs gen, I know it's a pain, and I never got as far as versioned docs - if you crack it I should probably see how + maybe do the same for the (non RTD) docs for the shoebot project.

[sgillies]

@Rotzbua my first impression is very positive. I would also prefer sphinx over, say, mkdocs, because of familiarity with sphinx. I have two questions:

• Did you approach this differently from what is described at https://bylr.info/articles/2022/05/10/api-doc-with-sphinx-autoapi/? Don't dive into that unless you want to, I'm only asking if you've already read that post.
• My thought would be to host at Read the Docs. Are you okay with that?

[Rotzbua]

Did you approach this differently from what is described at https://bylr.info/articles/2022/05/10/api-doc-with-sphinx-autoapi/? Don't dive into that unless you want to, I'm only asking if you've already read that post.

During a short research I also came across this article. However, the changes and customizations were too much for me. My PR contains only minimal changes to keep it maintainable and clear. The Github action is only copied from the examples.

My thought would be to host at Read the Docs. Are you okay with that?

I always try to avoid third-party vendors whenever possible. But if you are more familiar with it, why not?

[sgillies]

Here we go: https://affine.readthedocs.io/en/latest/.

Thank you @Rotzbua !

[stuaxo]

Fantastic work, thanks all!