Setup Documentation generation (readthedocs)

[MartinThoma]

No description provided.

[foarsitter]

Read the Docs is used for documentation. I tried to run the steps listed here: https://cookiecutter-hypermodern-python.readthedocs.io/en/2022.6.3.post1/quickstart.html#read-the-docs but the repository doesn't popup in the list. @MartinThoma can you give it a try?

[bosd]

I didn't have much luck with setting this up either.
@MartinThoma Can you make try?

[bosd]

@MartinThoma Can you please attend to this?
Maybe delegate some of the super powers to other contributors 🙏

[bosd]

We could also make the switch to mk docs as outlined here by @nmstoker .
Which looks really nice. for a preview see:
https://about.nmstoker.com/camelot/

What are your opinions, Do you guys agree to make the switch to mkdocs?

Likely we can host it on github pages.
Anyway, we need your super powers of @MartinThoma to set it up.

[stefan6419846]

Is GitHub pages really required in this case? It seems like RTD supports MkDocs as well: https://github.com/readthedocs-examples/example-mkdocs-basic Whether Sphinx, MkDocs, Doxygen, ... is used should not really matter in theory - I personally tend to prefer Sphinx with a more modern theme like furo, but it is always a matter of taste. Given there is an existing Sphinx structure/setup, I would probably stay with it while there are more important aspects to cover for now.

[bosd]

Is GitHub pages really required in this case?

No, I was just referencing it as an alternative. If it would be to difficult to setup a readthedocs.
But I assume "difficulty" is is not the reason why it is'nt setup yet.
Likely it's due to the lack of time and people with the authorization to do so.

@MasterOdin and @Lucas-C are co-owners of this organization. Myabe they can help.

Given there is an existing Sphinx structure/setup, I would probably stay with

Yes, makes sense to put the already in place mechanism at work.
I hope we can have it up and running soon. So the world could know we exsists. 😉

[MasterOdin]

This is the first I'm seeing this issue.

I'd love to help, but I'm not an owner on the organization (only @MartinThoma, @Lucas-C, and @mstamy2 are), so I'm a bit limited in how much I can help. I can import and setup the project on RTD, but I wouldn't be able to setup the webhook on GH so that new pushes to main (or tags or whatever) would appropriately trigger RTD builds. I can setup a project though on RTD, and invite @bosd, though then one of us would need to do manual builds as necessary, which definitely feels tedious and best avoided.

Is GitHub pages really required in this case?

The nice thing about using GH pages would be that you'd only ever need maintainer permissions to do anything with it, vs RTD which has its own set of permissions, which does raise the barrier of adding new projects. Biggest downside would be a slightly uglier URL (e.g. pypdf_table_extraction.readthedocs.io vs py-pdf.github.io/pypdf_table_extraction), but I'm not sure that's really that big of an issue.

[Lucas-C]

Hi

Sorry for the delay in answering.

There is a quick overview of the documentation that we currently have around @py-pdf:

• https://py-pdf.github.io/ - Source: https://github.com/py-pdf/py-pdf.github.io - Made using Pelican - Hosted on GitHub Pages
• https://py-pdf.github.io/fpdf2/ - Source: https://github.com/py-pdf/fpdf2/tree/master/docs - Made using mkdocs - Hosted on GitHub Pages - Doc is built AND published in GitHub Actions CI pipeline: https://github.com/py-pdf/fpdf2/blob/master/.github/workflows/continuous-integration-workflow.yml#L71
• https://pypdf.readthedocs.io/en/latest/ - Source: https://github.com/py-pdf/pypdf/tree/main/docs - Made using Sphinx - Hosted on ReadTheDocs - Doc is built in CI pipeline source: https://github.com/py-pdf/pypdf/blob/main/.github/workflows/github-ci.yaml#L169
• Not hosted yet - Source: https://github.com/py-pdf/pypdf_table_extraction/tree/main/docs - Made using Sphinx

I can setup the same workflow as for https://github.com/py-pdf/fpdf2, using a GitHub Actions pipeline to build & publish the documenation from this repo main branch onto GitHub Pages.

What do you think?

[bosd]

@Lucas-C
Thanks for your thorough reply.

If you have the authorization to setup the secrets to publish to readthedocs that will do it for now.
As a sphinx setup and publishing pipeline already is in place in this repo. (as this repo uses the following template cookiecutter-hypermodern-python)
It is only a matter of configuring it.

In the background I'm preparing a big pr, updating the documents.
(based upon the current config/docs)
Hope to have something ready in the coming days.

(While your'e at it, please also update the documentation url).

[Lucas-C]

Hi

I have imported this project on ReadTheDocs, using the main branch as reference:
https://pypdf-table-extraction.readthedocs.io

I also edited the URL mentioned in the "About" section on the GitHub project homepage,
as you suggested @bosd 👍