Remove some MkDocs log noise #1815
Merged
Conversation
This file contains 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
This was referenced Dec 7, 2023
StevenMaude
force-pushed
the
steve/remove-some-mkdocs-log-noise
branch
from
4897ff5 to
ba74727
Compare
Deploying with
|
| Latest commit: |
19ca009
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://935bac71.databuilder.pages.dev |
| Branch Preview URL: | https://steve-remove-some-mkdocs-log.databuilder.pages.dev |
|
Checked the links by hand in the ehrQL preview, and a preview of the OpenSAFELY documentation site that incorporates this ehrQL branch. |
(Yes, that doesn't sound like a contradiction at all.) Files in the top-level `/includes/` directory are actually included by the snippet support in pymdown-extensions, instead of directly included. This exclusion is to: * prevent the `includes/` directory from being included as built HTML pages themselves (which is in addition to their use as snippets in other built HTML pages) * allows suppressing of MkDocs warnings from these pages for `mkdocs build` and `mkdocs serve --clean`. (These warnings are because the relative links in the `includes/` source don't point to their intended actual links in the source directory, but they do when included as snippets.) The preceding `/` in `/includes/` is to exclude only the top-level `/includes/` directory to keep the exclusion rule specific; the option uses a `.gitignore` pattern format. See https://www.mkdocs.org/user-guide/configuration/#exclude_docs
This suppresses more MkDocs log noise. These pages are intended to be included, but are currently listed on a index-style page that gives more context.
Some of the existing links work in the ehrQL docs build, but not the main OpenSAFELY documentation site. This is because: * some of the existing links are either absolute links to the URL root, or relative paths that go the URL root, before descending * the ehrQL docs build preview has all the content at the URL root, and not, like the OpenSAFELY documentation site, in `/ehrql/`, so there's a mismatch of the depth of URLs there It would be good to make the two sites consistent: that is, make the ehrQL preview actually have URLs like: `/ehrql/how-to/…` instead of `/how-to/…` — it would remove the possibility for this kind of broken link.
This does not change the rendering, but does remove the MkDocs warnings. It uses a `.md` suffix, so MkDocs can find the file, and adjusts the relative path.
* Use code formatting * Remove rogue trailing quote
This link is broken in two ways: * it's an absolute link, which doesn't work in the OpenSAFELY documentation (but does in the ehrQL preview) * it always links to the `core` schema, whereas the intent is probably to keep the link to the same schema — this appears for `tpp`, for example
StevenMaude
force-pushed
the
steve/remove-some-mkdocs-log-noise
branch
from
ba74727 to
19ca009
Compare
|
I've left the |
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.
The MkDocs logs when serving or building the documentation are noisy, and are at least a screenful of information for me on my display configuration.
This hides information that might actually be useful to people when working on the documentation: new problems that might have been introduced when editing aren't obvious.
This PR reduces, but does not entirely remove, the noise by:
Other notes
just docs-serve --clean— this takes account of theexclude_docsoption I've configured inmkdocs.yml. This excludes theincludes/directory, which is a source of multiple false positives. Perhaps we should make--cleanthe default injust docs-serve? (Sometimes people might want to preview excluded documents, such as adrafts/directory, which is why this is not the default MkDocs behaviour.)/how-to/…, while the OpenSAFELY site has paths like/ehrql/how-to/…. Because of this, some links — either from absolute paths or from relative paths that reach the URL root — work in the ehrQL preview, but are broken on the OpenSAFELY site. I'm not sure why the OpenSAFELY link check doesn't catch these. I opened an issue for restructuring the ehrQL preview.includes/as accessible pages. Because we still have the quirk of having to duplicate our configuration, we should configure it there too.ehrql/docs. This might be a little bit trickier to get right, so I've opened an issue to document the problem, and it can be a separate PR.