Tvheadend

Flole Systems wrote:

There is https://docs.tvheadend.org/ but I don't think anybody has access to it anymore, so it doesn't really matter how it's built. We could use GitHub pages though, and automatically build it and upload it to some GitHub-page.

Flole Systems – I have started a new topic to discuss documentation.

TL:DR

• https://docs.tvheadend.org/ is hosted on GitHub.
• tvheadend-documentation seems to be the master documentation repository.
• There are scripts to export the master documentation onto docs.tvheadend.org and into the application documentation source code.
• The application documentation seems to be more up-to-date than the master documentation.
• Seek out 'ProfYaffle' on GitHub, they may know more.

My findings:

I did some research into the documentation.

Taking 'Bouquets' as an example: https://docs.tvheadend.org/webui/config_bouquet/

I found that the start of the web page was largely word-for-word equivalent to what is in a GitHub application source file.

https://github.com/tvheadend/tvheadend/blob/master/docs/class/bouquet.md

However, it differs significantly after the first few paragraphs.

At the top of the 'docs.tvheadend.org' page, there is a link to GitHub. That takes you to another repository called 'tvheadend-documentation'.

https://github.com/tvheadend/tvheadend-documentation/blob/master/docs/webui/config_bouquet.md

The contents of this file seem to be a very good match.

Having a look at the 'Installing your tuners' topic. It seems that the two versions were similar but different.

It looks like there are two sources of documentation in GitHub: 1) The documentation compiled into the WebUI and 2) The documentation available in 'docs.tvheadend.org'.

Generally speaking, the files in the application repository are more up-to-date than the files in the documentation repository, however, this is not universal.

The style of the documentation in the WebUI seems to be slightly terse and probably targeted at somebody who needs a quick reference in the WebUI trying to make changes.

The style of the documentation on 'docs.tvheadend.org' (hosted on GitHub), however, seems far more detailed like a user manual. Both sets of documentation also seem to have a slightly different organisational structure that seems to have had a common source, however, they have diverged over time.

Bringing these two sets of documentation into harmony may prove to be challenging. Deciding which one is the 'master' and then copying that to other one would probably not work as there appears to be some embedded sections as follows:

Nice, user-friendly, introduction and header
<Copy section from application documentation>
Some more user-friendly text.

In the 'to do' page on the documentation repository:

https://docs.tvheadend.org/todo/

There is an interesting clue. One item reads: 'Generate new webUI help pages and push them to the tvheadend repo'.

This indicates that at one point in time, the 'documentation' repository was the master repository that was fed into the application repository's documentation section. Unfortunately, it seems that this hierarchy has been reversed and that the application documentation is now more up-to-date.

The documentation website mentions that it was created via 'MkDocs'. There is also a link on how to update the documentation.

http://docs.tvheadend.org/Appendices/doc_update/

The documentation is in 'md' format and the files are managed through GitHub. Once changes have been merged, there is a script to run that builds the application help files.

The GitHub user 'ProfYaffle' seems to have been active in the documentation repository as recently as June 2023. Perhaps they may be able to add some insights.

Based on the types of questions that are asked by newcomers to the forum, what are the most important area of the documentation? Perhaps we could start there.

Apart from getting GitHub and MkDocs working on a system, the whole documentation text comparison and editing process would seem to be straight forward for a user without technical skills. It would be very long and tedious, but not technically difficult. Clear and precise direction will be required as well as access to development resources to answer technical questions that may arise.