search

dracut-ng / dracut-ng

dracut - the event driven initramfs infrastructure
https://dracut-ng.github.io
GNU General Public License v2.0
81 stars 62 forks source link

Fix publishing of documentation site #723

Open ianw opened 3 days ago

ianw commented 3 days ago

It looks like possibly github pages isn't enabled for the doc site to publish from https://github.com/dracut-ng/dracut-ng/commit/77e0571c29256e6951cc9a48c0d2ff5015a5f6b3 (this was a bit of a guess how to do it, copied from docs)

https://github.com/dracut-ng/dracut-ng/actions/runs/11375197026/job/31645405554 says

Error: Get Pages site failed. Please verify that the repository has Pages enabled and configured to build using GitHub Actions, or consider exploring the `enablement` parameter for this action.
Error: HttpError: Not Found
LaszloGombos commented 3 days ago

https://github.com/dracut-ng/dracut-ng/actions/runs/11375208938

Anything else is missing ?

Version number could use some love I think - https://dracut-ng.github.io/dracut-ng/

ianw commented 3 days ago

Ok let me look at that version!

LaszloGombos commented 3 days ago

Ok let me look at that version!

https://github.com/dracut-ng/dracut-ng/blob/main/tools/release.sh#L56 for motivation..

Ideally if the doc does not change, it should not change the generated html IMHO.

ianw commented 3 days ago

So it is coming from DRACUT_MAIN_VERSION which should just be the tag

DRACUT_MAIN_VERSION ?= $(shell env GIT_CEILING_DIRECTORIES=$(CURDIR)/.. git describe --abbrev=0 --tags --always 2>/dev/null || :)

but when I look at https://github.com/dracut-ng/dracut-ng/actions/runs/11375414798/job/31646026637 it's deliberately not pulling tags?

Fetching the repository
  /usr/bin/git -c protocol.version=2 fetch --no-tags --prune --no-recurse-submodules --depth=1 origin +e37c67f6f573ca5a15e88e5899e92ce1a8582bac:refs/remotes/origin/main
  From https://github.com/dracut-ng/dracut-ng
   * [new ref]         e37c67f6f573ca5a15e88e5899e92ce1a8582bac -> origin/main

hrm...

ianw commented 3 days ago

Only a single commit is fetched by default, for the ref/SHA that triggered the workflow. Set fetch-depth: 0 to fetch all history for all branches and tags.

https://github.com/actions/checkout ... that is an interesting choice ...

LaszloGombos commented 3 days ago

Should we limit when publish runs (e.g. when there is a change under docs/ ) ?

https://github.com/dracut-ng/dracut-ng/blob/main/.github/workflows/publish.yml#L4

Similar to e.g. https://github.com/dracut-ng/dracut-ng/blob/main/.github/workflows/codeql.yml#L11

See https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore

@ianw If you planning to activly work more on docs more (please do if you can), we should also consider disabling Integration test for docs-only changes.

LaszloGombos commented 3 days ago

Would be great to link the wiki (https://github.com/dracut-ng/dracut-ng/wiki) from the doc site (https://dracut-ng.github.io/)

Wiki is already linking to the doc site (just fixed it).

ianw commented 3 days ago

Should we limit when publish runs (e.g. when there is a change under docs/ ) ?

https://github.com/dracut-ng/dracut-ng/blob/main/.github/workflows/publish.yml#L4

I guess you don't want a release to be out of sync with the doc site. I'm sure it's possible but it seems like a lot of matching to figure this out?

@ianw If you planning to activly work more on docs more (please do if you can), we should also consider disabling Integration test for docs-only changes.

I think I did that in https://github.com/dracut-ng/dracut-ng/pull/727

Do you have any idea how we can have changes build the site and speculatively publish it? I know how to do it with gitlab, where the site becomes an artifact of the pipeline, but I'm not familiar enough with github to know ATM

edit: https://github.com/dracut-ng/dracut-ng/pull/729 is my guess?

jozzsi commented 3 days ago

Perhaps we can also start moving some of the documentation from the wiki to the newly created doc_site/modules/ROOT/pages/. This would not only make the documentation site more complete, but would also solve the problem that I do not have permission to edit the wiki, but I can create PR's against the document if it is in the git tree.

ianw commented 2 days ago

Perhaps we can also start moving some of the documentation from the wiki to the newly created doc_site/modules/ROOT/pages/

I'm a big fan of this approach -- the github wiki isn't too bad as you can git clone it, but overall treating docs-as-code is I think the better long-term approach. It gets reviewed in the same way as code, can have CI jobs, etc. and overall has more of a chance of being updated alongside changes being in the same tree IMO

I've read through the wiki and I think that https://github.com/dracut-ng/dracut-ng/pull/741 should capture most of what seems unique in there into the generated doc site

jozzsi commented 2 days ago

@ianw fantastic work. Thanks. What do you think of using README.md as an input as well for the generation ? I hope we can keep the README.md where it is now (or maybe do some link magic within the repo).

ianw commented 2 days ago

What do you think of using README.md as an input as well for the generation ? I hope we can keep the README.md where it is now (or maybe do some link magic within the repo).

I guess the problem is that will need to be an asciidoc to work with the rest of the site.

IMO the README.md sort of sits alone as a quick discussion of the source (if you've cloned the tree) and with links to the docs -- in this day and age it's main use is probably as the github landing page where the github MD is most suitable. So to me a little duplication in there, but mostly having it clearly point to the generated documentation is OK

It would be kind of cool to get the NEWS bits published too. I've never found a great tool that seems to do that with asciidoc. Towncrier does MD, and there's sphinx options for rst -- but i'd be interested if anyone has something that works with an asciidoc workflow