Should the HTML documentation be dropped?

[michaelpq]

This is mainly a question to @rjuju, @mikecaat and @horiguti. I have noticed that little attention is being brought to maintaining the docs, and the English versions really need a brush-up, in my opinion.

Is the HTML documentation still relevant these days knowing that this is just a copy-paste of README.md? Would it be better to avoid the duplication and drop that?

FWIW, using something as pandoc makes it really easy to generate some HTML documentation from a md file, so we could always do that if necessary. At the end, I would like to see the duplication gone to ease the long-term maintenance, only on HEAD of course. The back-branches do not stress me much on this matter.

[rjuju]

IMHO manually maintaining an html documentation or the same content in multiple format is doomed to fail.

The usual answer for that is to rely on some existing tooling to make the conversion. I think that readthedocs would be more appropriate here, as it can be configured to automatically regenerate the docs for each commit, and handle multiple branches. Markdown is supported using MkDocs, see https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html.

I'm personally using RTFD.io for my extensions and have been generally happy with it, although at that time markdown wasn't supported, only reStructuredText using python sphinx.

[michaelpq]

IMHO manually maintaining an html documentation or the same content in multiple format is doomed to fail.

Agreed.

I'm personally using RTFD.io for my extensions and have been generally happy with it, although at that time markdown wasn't supported, only reStructuredText using python sphinx.

github is happy enough if you have a README.md in the tree. Do you think that pg_hint_plan is worth having a more complicated structure, among multiple files? Based on the size of the current docs that has been around for many years, I would say no, but perhaps future expansion of the documentation would make sense in the long-term.

[xzilla]

I also agree the ideal is a source file that is easily readable/editable by humans which can then be transformed into other formats as needed. To that end, I think we need to understand what are the use cases for the html versions of the docs? Presuming the markdown/github combo isn't enough and they are still needed, is it enough to just do a build on the markdown file into a single html file, which I think is possible through a GitHub action, so no additional tools required.

[rjuju]

Do you think that pg_hint_plan is worth having a more complicated structure, among multiple files? Based on the size of the current docs that has been around for many years, I would say no, but perhaps future expansion of the documentation would make sense in the long-term.

pg_hint_plans starts to be complex enough that it might be worthwhile to provide some additional documentation (quickstart, limitations, deeper usage and so on), so keeping a README shorter may be better.

Presuming the markdown/github combo isn't enough and they are still needed, is it enough to just do a build on the markdown file into a single html file, which I think is possible through a GitHub action, so no additional tools required.

That's literally what readthedocs is providing, and also hosts the built documentation.

[michaelpq]

pg_hint_plans starts to be complex enough that it might be worthwhile to provide some additional documentation (quickstart, limitations, deeper usage and so on), so keeping a README shorter may be better.

Okay. I was looking at what you have been doing with hypopg and doing something similar with the structure of the docs is fine by me: short README and a subdirectory called docs/ separated into various sections.

The way the documentation is hosted is something that seems less urgent seen from here, but if we can automate its build and the flow to publish it that's really better. I don't know if this can be achieved with the existing github actions, though, but that can happen incrementally once the structure of the docs is properly reworked.

As a start, what about splitting the current README.md?

[rjuju]

if we can automate its build and the flow to publish it that's really better. I don't know if this can be achieved with the existing github actions, though, but that can happen incrementally once the structure of the docs is properly reworked.

you can just setup a GH webwooks on the wanted events (e.g. push) pointing to the RTFD.io dedicated API, and then it will just work, providing that you configure a project there with and set the wanted branch (it does support multiple branches, multiple versions, multiple languages...). As long as you write your documentation in the correct format (so works with python mkdocs) it can be added anytime in a few minutes.

As a start, what about splitting the current README.md?

+1, as long as the README still contains some minimal pointers to use the extensions and references to full documentation.

[michaelpq]

+1, as long as the README still contains some minimal pointers to use the extensions and references to full documentation.

Of course.

So, here is the plan:

• Split and reformat README.md, creating a docs/ with a set of .yst files. Fine for me to stick with a format you have used in the past. That's new to me.
• Remove the html docs, removing as well the Japanese version
• Have a github action and optionally publish them somewhere.

How does that sound?

[rjuju]

I think we should stick with markdown rather than reStructuredText. It's more wildly used and it's arguably way more readable when looking at it with a simple text editor. If I had to do it again for HypoPG or other extension I would rather choose that, but that boat already sailed unfortunately.

I can work on that to see if I can get a decent rendering of the split documentation using mkdocs without too many obscure syntax and decide if we go this way.

For eventually publishing the documentation I "reserved" the pg_hint_plan name on RTFD.io (https://readthedocs.org/projects/pg-hint-plan/) so we will just have to add the webhook once the documentation is reaady (administrator right is needed for that).

[rjuju]

FTR I spent a bit of time setting up an mkdocs version of the README, split in a file per section, to get a basis for discussion.

I pushed a doc branch on my fork, available at https://github.com/rjuju/pg_hint_plan/commits/doc, and temporarily configured the RTD to point there, so the built docs are available online: https://pg-hint-plan.readthedocs.io/en/latest/

You can simply build them locally if you prefer, you just need to pip install -r docs/requirements and then either mkdocs server or mkdocs build, as seen in https://www.mkdocs.org/getting-started/.

[michaelpq]

FTR I spent a bit of time setting up an mkdocs version of the README, split in a file per section, to get a basis for discussion.

I was looking at your commit set and that seemed rather neat to me. If you wish to apply something directly into the tree, I'd be fine with that knowing your experience on the matter. If you want an extra pair of eyes, feel free as well to drop a pull request ;)

[rjuju]

Happy to hear that :)

I guess I will still create a pull request to make sure that everyone is ok with the few details (like the mkdocs.yml and the index.md that duplicates the TOC), and discuss how much we want to backpatch it (and then double check that RTD handles it correctly).

[michaelpq]

Sounds good to me!