Build docs to gh-pages with github actions

[idbrii]

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.

[AntumDeluge]

@idbrii Thanks for this. I have started using it for my own projects.

[alerque]

Thanks for this contribution. I'll look it over, but it might be WE before I am able to properly evaluate.

[AntumDeluge]

This needs a rebase I believe.

[Tieske]

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

[AntumDeluge]

Workflows can be configured to only deploy with new tags:

on:
  push:
    tags:
    - '*'

[alerque]

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:

1. Until we have separate versions, our documentation site should absolutely be for the last released version, not master.
2. It should identify the release it is documenting.
3. We should not be polluting master with 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.

[AntumDeluge]

Change this to:

 on:
-  pull_request:
-    branches:
-    - master
   push:
-    branches:
-    - master
+    tags:
+    - 'doc-v*'

... (or something similar) and documentation can be versioned by creating tags prefixed with doc-v:

$ git tag doc-v1.4.6

This way, docs will only be rebuilt on gh-pages branch when one of these tags is pushed.

[Tieske]

@alerque I'd love to see multiple versions of the docs generated 👍

[AntumDeluge]

@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

[AntumDeluge]

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.

[idbrii]

@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 .

[alerque]

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.