Improve documentation templates #618
Conversation
Dockerfile
Outdated
| # Now the "docs-template-testing" image, to check if the docs are up to date | ||
| FROM --platform=${TARGETPLATFORM} build as docs-template-testing |
There was a problem hiding this comment.
Does this means we run the docs-template-testing bits each time we want to run a test case (using e.g. make tests/pagila) on our local systems?
There was a problem hiding this comment.
No. Docker is clever enough to skip build stages that are not used. All thanks to the default backend (since last February) BuildKit for Docker.
See the list at the beginning of the page for BuildKit
There was a problem hiding this comment.
I see. I think I would still prefer it if we had a separate Dockerfile for the docs, does it make sense to split things that way?
There was a problem hiding this comment.
Docker does a poor job managing dependencies across multiple Dockerfiles. I created a new Dockerfile.tests file with a copy of our build stage so that we can hit docker build cache.
hanefi
force-pushed
the
docs-improvements
branch
from
81fba26
to
2c91e0a
Compare
.github/workflows/run-tests.yml
Outdated
| - name: Check that docs are up to date | ||
| run: | | ||
| docker build --file=Dockerfile.tests --tag tests . && \ | ||
| docker run tests |
There was a problem hiding this comment.
We now have two main Dockerfile, the one that we use to run tests and the one that we use to build documentation. Why is the documentation one named Dockerfile.tests?
There was a problem hiding this comment.
Currently it does not build docs. It only checks (or tests) if the documentation templates are up to date.
Is there any other name you'd prefer? Let me move this file to ci/Dockerfile if it will make it clear that it is not a main Dockerfile.
There was a problem hiding this comment.
Well I think I would prefer ci/Dockerfile.docs (the move to ci/ is nice). And if the contents have to contain a copy/paste version of the main Dockerfile, can we script that, use a template/include mechanism (only in the ci/ version, leave the main Dockerfile alone/unchanged)?
There was a problem hiding this comment.
Moved the file to ci/Dockerfile.docs.template. One can run the following command to generate the final Dockerfile that is ignored in the git worktree:
cat Dockerfile ci/Dockerfile.docs.template > ci/Dockerfile.docsI do not expect users to actually use this dockerfile in any way. I think make update-docs should be the command to run on development environments.
hanefi
force-pushed
the
docs-improvements
branch
from
1985a1c
to
59dac3f
Compare
- Adds CI to check that the documentation templates are up-to-date. - Add a new `help` command to the documentation templates. This command prints the help message for all the sub-commands of `pgcopydb` in a single file. This is useful for users who want to see all the sub-commands in one place. - Remove dependency on installing the binary before updating the documentation templates. This allows users to update the documentation templates without installing the binary. One can set the `PGCOPYDB` environment variable to point to the binary to use for updating the documentation templates. - Fix a casing issue in command descriptions. The first letter of the first word in the description of each command should be capitalized.
helpcommand to the documentation templates. This command prints the help message for all the sub-commands ofpgcopydbin a single file. This is useful for users who want to see all the sub-commands in one place.PGCOPYDBenvironment variable to point to the binary to use for updating the documentation templates.