Implement multi docs #70
Conversation
galleon
commented
Oct 7, 2021
- Add workflow to generate doc
- Add new dropdown widget in navbar to select doc version
|
Why is a new workflow needed? We already have build.yml and release.yml. BTW release.yml should have been modified to not deploy. |
|
There are at least 2 ways to build versioned documentation:
Your commit message for 5ab99ab is way too terse. You should describe the different options, and why you implemented it that way. |
Will improve commit description. |
|
|
At the moment docs.yml is still there, please push your changes before writing comments. |
| ), | ||
| handleSelected: (input, event, suggestion) => { | ||
| const {pathname, hash} = new URL(suggestion.url); | ||
| const routepath = pathname.replace('/NotifyBC', ''); |
- generate a static web site on GH pages for each tagged release and for master (dev version) - create vuejs component to choose selected version - modify default theme to add version component in navbar - move all vuepress related packages as dev dependencies
- fix base url do avaoid double slash - display dev instead of main in dropbox for doc version selection
- use latest version of publishing GH action - change target directory on GH pages for release documentation - generate doc only for master branch
| branch: gh-pages # The branch the action should deploy to. | ||
| folder: docs/.vuepress/dist # The folder the action should deploy. | ||
| target-folder: ${{ env.DOCS_VERSION_PATH }} | ||
| commit-message: Publish documentation |
There was a problem hiding this comment.
Same comment as before, there is no reason to upgrade this action in this PR, do it in a separate PR. Here you only have to add TARGET_FOLDER.
There was a problem hiding this comment.
Having multiple PRs might be desirable but we need to find a compromise between related work and time needed to review PRs. This actions needed to be modified and I took this opportunity to update to the latest version (same in build.yml btw).
There was a problem hiding this comment.
This is the exact opposite, putting unrelated changes into the same PR makes review much more time consuming.
| @@ -227,6 +227,7 @@ jobs: | |||
|
|
|||
| build-docs: | |||
| needs: [test-unix, test-macos, test-windows] | |||
| if: ${{ github.ref == 'refs/heads/master' }} | |||
There was a problem hiding this comment.
Documentation must also be built for PRs.
It could also be handy to temporarily deploy them, for instance this would be useful for this PR.
There was a problem hiding this comment.
The request is to generate doc for dailys based on changes on master and for releases (tagged versions). If I was to regenerate docs for each and every PR or branch this will soon be messy. Why don't we keep it simple ?
There was a problem hiding this comment.
Build-docs step is currently performed by all PRs. You are modifying this behavior, this is mentioned neither in commit message nor in this PR, so it is unclear whether this change is intentional or not. In any case, skipping this step is a bad idea.
| "scripts": { | ||
| "docs:dev": "(cd docs && python autodoc.py) && vuepress dev docs", | ||
| "docs:build": "vuepress build docs" | ||
| }, |
There was a problem hiding this comment.
Please do not reindent while making changes.
Please do not mix different issues in the same PR; if you want to change how vuepress is launched, do it in a separate PR.
There was a problem hiding this comment.
yarn run docs:dev is simply not working if you don't launch python autodoc.py first.
There was a problem hiding this comment.
It had always been that way without any problem. You are making changes without explanation, this makes code review harder. Again this PR is about generating versioned documentation, and all these unrelated changes divert us from discussing the main points.
|
Closed when modifying branch multi_docs on my fork. |