Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Setup docs building in CI #72

Merged
merged 3 commits into from
Mar 12, 2021
Merged

Setup docs building in CI #72

merged 3 commits into from
Mar 12, 2021

Conversation

refi93
Copy link
Collaborator

@refi93 refi93 commented Mar 12, 2021

Motivation: Don't commit autogenerated docs as it can generate unnecessary conflicts and commit the docs to a separated gh-pages branch instead from CI.

Moreover, allow for multiple versions of the docs (by package version number) to reside one besides another so it's easy to navigate between them. Unfortunately, typedoc doesn't seem to support versioning: TypeStrong/typedoc#737

Explanation:

  • created a CI job that builds the docs into a separate folder for the current version of the package
  • added gh-pages development dependency in order to "deploy" the docs built into a dedicated gh-pages branch which is then hosted as a github page
  • the docs reside in a folder named by the version number of the package. I added into CI a command to create an index.html file such that it redirects the visitor of the github page root to the latest version of the package. Users then can navigate to earlier versions by flipping the version number in the URL (I tried also generating a listing of files but my efforts led nowhere and the current approach seemed like an easy win)

package.json Outdated
@@ -71,7 +72,7 @@
"clean": "bash ./script/clean.sh",
"build": "bash ./script/build.sh",
"watch": "bash ./script/watch.sh",
"gen-docs": "yarn typedoc",
"gen-docs": "yarn typedoc --out docs_generated",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is typedoc config where you can specify out

@refi93 refi93 merged commit 88dcea0 into develop Mar 12, 2021
@refi93 refi93 deleted the docs-building-setup branch March 13, 2021 01:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants