Documentation now on Github "pages"

[dl8dtl]

After some discussion with Hans, I prepared the documentation to go to Github "pages":

https://avrdudes.github.io/avrdude/

The toplevel page is a "switch" page to allow linking documentation for individual releases. As the pre-Github release 6.4 is the latest official release right now, I added its documentation there as well as a snapshot of the current development version. I also tried to make the current documentation look a little more pleasant by tweaking texinfo's CSS a bit.

Documentation for historic releases can still be obtained from Savannah.

Toplevel README.md links to the new place.

Technically, all this is located in the main repository, but it's well hidden in the onlinedocs branch, and there, inside the docs/ subdirectory. This directory is supposed to be maintained solely within that branch, not to be merged back to the main branch.

[per1234]

I find it confusing that there is an outdated copy of the source code stored in the onlinedocs branch.

Why not use that branch for the documentation content alone?

[MCUdude]

@dl8dtl this is a good point. Perhaps just remove all source code from this branch except the HTML stuff needed for the website?

[dl8dtl]

Well, could do that, but why the heck would anyone want to checkout a branch named "onlinedocs", and then expect usable source code inside?
After all, the onlinedocs need a branch in the regular tree, that's how Github works.

[MCUdude]

Well, could do that, but why the heck would anyone want to checkout a branch named "onlinedocs", and then expect usable source code inside?

Not at all, it's just that there's no reason to host an outdated version of the source code along with updated docs.

[dl8dtl]

I still think that the entire requirement of a branch (vs. a separate repository) is a bit of a crock, but I removed the source code from it now.

[dl8dtl]

Well, with the removal of src/, the (implicitly triggered) CI fails now, obviously.

https://github.com/avrdudes/avrdude/actions/runs/2224773769

@mariusgreuel Can you tell us where to exclude the onlinedocs branch from CI builds?

[mariusgreuel]

This directory is supposed to be maintained solely within that branch, not to be merged back to the main branch.

IMHO, I find using a separate branch for the docs a little odd. What is the reason for not putting it on main?

[per1234]

The great thing about having documentation stored alongside the active code is that the documentation can be updated in the same commit that makes a code change necessitating a change to the documentation. This way the two are always in sync and it is easier to make sure documentation updates are not forgotten.

When they are separate, it becomes difficult to remember that there is a required follow-up documentation update conditional on the merge of a PR.

[dl8dtl]

The great thing about having documentation stored alongside the active code is that the documentation can be updated in the same commit

We do have that already. docs/avrdude.texi and avrdude.1 (the man page) are along with the code, and are updated together with code.
The onlinedocs branch is only to keep compiled versions of the documentation (HTML tree and PDF), including those of previous releases.

[per1234]

 workflow_call:
   branches-ignore:    
     - 'onlinedocs'

The branch filter is only supported for the push and pull_request event triggers of the workflow

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore.

[dl8dtl]

This directory is supposed to be maintained solely within that branch, not to be merged back to the main branch.

IMHO, I find using a separate branch for the docs a little odd. What is the reason for not putting it on main?

(Sorry, I accidentally edited your message rather than quoting it. Now, the previous contents appears to be lost.)

As it contains the compiled versions (possibly many of them) of the docs, it would clutter the source tree with a bunch of irrelevant stuff.

As I understood the "pages" documentation, you can only chose between either the top-level directory, or a fixed docs subdirectory, and it must be in the main repository lest it would get a different name in the "pages" URL (i.e. it's then basically a different project). Thus, the option to chose a branch was the most appealing one to me.