Repository navigation
Update documentation, README, and contributor guide - #67
Merged
Merged
Conversation
Re-platform the documentation from reStructuredText to Markdown.
Remove Sphinx, its configuration, its Makefiles, and the generated
docs/include tree. GitHub renders the pages directly.
Command help stays generated. Each page marks where a help block goes:
<!-- BEGIN HELP: pgcopydb clone -->
```
```
<!-- END HELP -->
docs/update-help-messages.sh rewrites the text between the markers, so
prose and help share one page per command. make update-docs and the CI
docs check work as before. The script now fails when a marker names a
command that does not exist.
Add markdownlint. Configuration in .markdownlint-cli2.yaml, run by
make lint-docs, checked in CI.
Update author attribution in the README, the docs landing page, the
contributor guide, and add a note on how this fork is maintained.
Correct the install page: container images at
ghcr.io/planetscale/pgcopydb, whose version tags carry no leading "v",
and a source build with the current Ubuntu 24.04 package list. Link the
migration-scripts templates.
Cover pgoutput in the plugin section. Add docs/operations.md for the
options this project adds for large migrations.
Remove the Sphinx man page step and the python3-sphinx build dependency
from the debian packaging. Remove the stale make docs target.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only. No code changes.
Re-platform
reStructuredText to Markdown. Sphinx,
conf.py, the docs Makefiles,.readthedocs.yamland the generateddocs/includetree are removed.19 hand-written pages and 11 reference pages convert; GitHub renders them
directly.
Command help stays generated. Pages carry
<!-- BEGIN HELP: ... -->markersand
docs/update-help-messages.shrewrites the block between each pair, so onepage holds both the prose and the help for a command.
make update-docsandthe CI docs check are unchanged. 57 help blocks across 10 pages.
Linting
.markdownlint-cli2.yaml,make lint-docs, one CI step. The image is pinned bydigest. Five rules are disabled with the reason recorded in the config. Nine
existing violations are fixed, including a duplicate heading that produced an
ambiguous anchor.
Content
guide, plus a note on how this fork is maintained.
ghcr.io/planetscale/pgcopydb, version tagscarry no leading
v, and a source build with the Ubuntu 24.04 package list.Links the migration-scripts templates.
pgoutput, the publication it manages, and theprivileges that needs.
docs/operations.md: deferred index builds, foreign key handling,same-table concurrency, restore tolerance, CDC disk use, source reconnects and
timeline changes.
Packaging
The debian build generated man pages with Sphinx. That step, the
override_dh_installmantarget and thepython3-sphinxbuild dependency areremoved. The package no longer ships a man page. The stale
make docstarget isremoved.
Checks
make lint-docs: clean across 21 filesmake check-docs: passes in the container, "Docs are up to date"