Document all the things

[nephros]

This is just to let you know that I am in the process of generating inline documentation for all the different PM components.

It started out with me wanting to inline comment some code, but ended up with a almost complete qdoc markup.

This is not finished at all (probably never will be), but it's in a previewable state, hence this draft PR.

Previews of the generated docs can be looked at here: https://htmlpreview.github.io/?https://github.com/nephros/patchmanager/blob/documentation/doc/generated/patchmanager/index.html

[nephros]

... one may also want to unsubscribe from push notifications, because I generate a lot of them with this branch.

When it's ready there will likely be quite some rebasing and squashing as well.

[nephros]

As can be seen in the footer, I am copying the Opal project in placing the generated docs under GNU FDL license. I hope this is OK for everybody.

[b100dian]

This is awesome - but do you plan to merge the comments you're writing within the existing source files and the html output together or split them in two - comments in main, generated docs in the documentation branch (much like a pages one)?

[nephros]

This is awesome - but do you plan to merge the comments you're writing within the existing source files and the html output together or split them in two - comments in main, generated docs in the documentation branch (much like a pages one)?

Good question - I have been pondering the same.

It is generated stuff, so formally it should not live in a repo.

OTOH we will want to "host" it so we need the files somewhere.

One way could be to have a seperate repo patchmanager-documentation or so. This could then be accessed though github.io or readthedocs or something.

GitHub action could build the docs from here, and submit a PR or commit to the other repo.

I guess packaging as RPM does not make much sense, unless of course we want .qhp files as well, which could be used in QtCreator/SailfishSDK...

[b100dian]

GitHub action could build the docs from here, and submit a PR or commit to the other repo.

Exactly. We can define a "pages" repo just for this. I didn't do this lately with github actions, but I did with woodpecker in codeberg, should be similar https://codeberg.org/sailmates/website/src/branch/main/.woodpecker.yml#L68 (the problem was: sources built a static website that gets commited to pages repo)

[Olf0]

As can be seen in the footer, I am copying the Opal project in placing the generated docs under GNU FDL license. I hope this is OK for everybody.

Yes, though the GNU FDL is very old and only aimed at the US-American jurisdiction, in contrast to the Creative Commons licenses which are internationally oriented (the same text for all jurisdictions with approved translations) legally much more modern and better phrased, plus allow for different variants to pick from ("CC BY-SA" is the equivalent of the GNU FDL). As always I do distrust any "or later" phrase since the GPLv3 license process (which resulted in fundamentally different and incompatible licenses to its predecessors, the GPLv2 licences), thus suggesting the CC 4.0 BY-SA.

Good question - I have been pondering the same.

I would suggest keeping it all in one repo (this one), the chosen location docs/generated is fine IMHO.

Similarly I strongly suggest not to depend on multiple service providers, hence do everything on the infrastructure GitHub provides: Publish the generated documentation on GH-pages at github.io, for which multiple GH-action examples exist, which can be copy&pasted with little adaption.

[b100dian]

I would suggest keeping it all in one repo (this one), the chosen location docs/generated is fine IMHO.

I don't agree - keeping the same repo yes, keeping in the same branch(es) as the code is way too much compared to, say, localization files. Same repo, "pages" branch or same org, "pages" repo.

Then again, I'm just commenting here, the doers should have precedence;)

Similarly I strongly suggest not to depend on multiple service providers, hence do everything on the infrastructure GitHub provides: Publish the generated documentation on GH-pages at github.io, for which multiple GH-action examples exist, which can be copy&pasted with little adaption.

Agreed. I was just linking that a similar 'push generated stuff to different repo (or branch)' was possible on another infrastructure. GH-pages feature is what I have in mind too, and that usually is a different repo or unrelated branch (no common ancestors).

[nephros]

I'll agree with @b100dian.

Any branch containig the doc/generated tree is potentially going to be:

• noisy, and
• changesets are going to be large and full of barely-human-readable diffs.

So we want to keep the code changelog/git hitory clean, docfiles should go into another branch.

Now I don't know if gihtub can do different "changes need four-eye review" settings per branch, but if not we want a seperate repo, as I'm sure no-one will want to review the documentation update PRs all the time.

Note that I'm taking about generated files only, documentation source, i.e. *.qdoc files and inline comments go through review as usual.

[nephros]

BTW, changed the licensing Footer to use CC-BY-SA as @Olf0 suggested.

[nephros]

Right, so I how have:

• [X] this Action to publish to GH Pages on push
• [X] a dedicated "orphan" branch for the Action to pull from
• [X] The Result of an Action run at nephros.github.io

What's missing:

• [x] not yet: an Action to:
  • check out "docs-generated"
  • pull from "documentation" or "master"
  • and generate the docs. We may make such an Action using the Coderus Docker image (plus: it has the SailfishOS html templates available), or anything that can run qdoc in a sane enough environment.
  • commit&push the results to "docs-generated"

I'm also in the progress of a major rebasing and cleanup to get rid of all the generated doc artifacts in the commit history of this branch.

[nephros]

Cleaned out all generated docs from history

[b100dian]

Now I don't know if gihtub can do different "changes need four-eye review" settings per branch, but if not we want a seperate repo, as I'm sure no-one will want to review the documentation update PRs all the time.

I'm not sure documentation needs to be reviewed. If it is output from the changes in the code comments, then that can be reviewed instead.

Second topic: Thanks for cleaning this branch - I am trying to find out what branches: ["./doc/generated"] and similarly branches: ["documentation"] actually mean, did you already run one of the new workflows?

Third, question: Are you aware that in this repo/org you can enable pages and specify a branch or repo for that? I am not sure I get what "they're currently deployed on nephros.github.io" means, why not do it here?

[nephros]

Now I don't know if gihtub can do different "changes need four-eye review" settings per branch, but if not we want a seperate repo, as I'm sure no-one will want to review the documentation update PRs all the time.

I'm not sure documentation needs to be reviewed. If it is output from the changes in the code comments, then that can be reviewed instead.

Yes what I wanted to say. In addition to source comments there are .qdoc and .qdocconfig files though which live in master and hence will have to go through review.

Second topic: Thanks for cleaning this branch - I am trying to find out what branches: ["./doc/generated"] and similarly branches: ["documentation"] actually mean, did you already run one of the new workflows?

The idea is to have sources in 'documentation' (for now, master in the future), have an action to generate doc artefacts from that, and commit/push them to 'doc-generated'.
That one is the content for GH Pages.

Third, question: Are you aware that in this repo/org you can enable pages and specify a branch or repo for that? I am not sure I get what "they're currently deployed on nephros.github.io" means, why not do it here?

I am aware, nephros.github.io is just for incubating the solution.

[nephros]

Discussion about deploying and using Actions can continue in #447

[nephros]

One more cleanup force-push: drop all the GH action commits, and their reverts.

So, I guess we don't squash-merge this but rather merge all of the seperate commits.

Should I add another round of squash/rebase/forcepush, or are we okay with 100+ commits?

[b100dian]

I would just use the Squash and merge option in this case;)