ldoc
ldoc copied to clipboard
lunarmodules
Build docs to gh-pages with github actions
Related #332.
Builds docs to the gh-pages branch on every push to master. Also updates all dead links to point to live ones (or ones that will be live after this is merged).
Builds the documentation for ldoc using the checked out version of ldoc and uses peaceiris/actions-gh-pages to publish.
Once merged, docs will be available on https://lunarmodules.github.io/LDoc
Currently, you can see the built docs on https://idbrii.github.io/lua-ldoc/manual/doc.md.html
After merging and the build cycles once, an owner needs to enable gh-pages on github: Settings > Pages and set "Source" to gh-pages and root.
Then all the dead links should be fixed. I'd recommend changing the project url in github to https://lunarmodules.github.io/LDoc/manual/doc.md.html which is the first useful page of the docs.
!! I didn't change the rockspec links because that change was already started in #332.
I think it's useful to have a guide for auto running ldoc, but maybe penlight would be a better example since it would have to install ldoc but it's publishing the docs to the repo itself instead of to a separate branch.
Thanks for this contribution. I'll look it over, but it might be WE before I am able to properly evaluate.
not sure about this, typically the gh-pages branch contains the published docs, and should have the docs for the latest released version. Not master imo. Typically I keep the generated docs in a /docs folder, but only update them on a release (also to not pollute each PR commit with docs changes).
I've been bitten by this several times, and must say I haven't made up my mind entirely yet... my 2cts
Workflows can be configured to only deploy with new tags:
on:
push:
tags:
- '*'
As @Tieske comments, this actually opens up a whole can of worms. The current documentation site makes no note about what version it documents, only what version of ldoc it was generated with. Presumable those are the same but it shouldn't be assumed. Really we should find a way to have versioned documentation (see e.g. how Rust crates document by version, mdbook for example).
In the mean time:
- Until we have separate versions, our documentation site should absolutely be for the last released version, not
master. - It should identify the release it is documenting.
- We should not be polluting
masterwith a bunch of doc commits, nor I think the gh-pages branch. At least until such a time as we have a dedicated docs namespace for the devel version we don't need an update to pages after ever commit. When we do have namespaces for different docs the docs should probably be in a different repo altogether.
More later (WE+) when I can review further. I'm sure there are things we can do to improve the current situation, but probably not in exactly this form.
@alerque I'd love to see multiple versions of the docs generated 👍
This could be accomplished by adding a command or shell script like the following to the workflow:
Old:
mkdir doc_builds
for tag in $(git tag | grep "^doc-v"); do
git checkout ${tag}
make doc-site
mv out doc_builds/${tag}
done
Edit: build_versioned_docs.sh
Here is a live example I threw together from my build_docs branch (which is this PR rebased on master with some changes to the workflow).
Note: "latest" is most recent doc tag (e.g. latest is the same as 1.4.6-dev).
Not sure why usage info didn't show up.
@AntumDeluge Nice work on the multiple versions! The mdbook example includes a version selector inside the doc page, so I guess ldoc would need to be updated to support built-in version selection. Maybe the spartan index page is sufficient for now because mostly you'd link directly to a specific version?
You might want to make the index link directly to manual/doc.md.html since that's where the primary content lives.
Not sure why usage info didn't show up.
I believe the usage shows up strangely because ldoc doesn't use a comment for usage.
At least until such a time as we have a dedicated docs namespace for the devel version we don't need an update to pages after ever commit. When we do have namespaces for different docs the docs should probably be in a different repo altogether.
@alerque I don't understand what you mean by namespaces (https://github.com/lunarmodules/LDoc-docs ?) but maybe the structure of AntumDeluge's gh-pages solves that problem.
The main thing that's missing now after AntumDeluge's work is showing the current project version on the generated doc page. I think we'd want that to be an argument to ldoc (instead of in config.ld) to make life easier for automation: --projectversion 0.1.0. Alternatively, we might be able to pass in via the existing --project .
I would be happy to see another PR that gets multiple-version output going for this repo and/or any LDoc project, but in the interest of getting URLs updated and a release out we'll go with just this building the current version for now.