Revisit allowing building the docs without access to "Material for MkDocs Insiders" #2677
Conversation
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
Yes, this does pretty much undo the "offline" part, but without this the docs can't build if the builder doesn't have access to the insiders' edition of mkdocs. Doing this as a first step to investigating if there's any possible way to achieve what we want here: - Anyone can build - They can build offline - They can build for maximum privacy If not, this step at least hits the first requirement. See Textualize#2629.
It looks like mkdocstrings will fail out if it can't download the inv files. Unless there's a setting where you can tell it "try, but if you can't grab them just don't try and create links" the approach here seems reasonable and has the same effect. Textualize#2629 (comment) for reference.
This was
linked to
issues
May 29, 2023
rodrigogiraoserrao
approved these changes
May 29, 2023
willmcgugan
approved these changes
May 29, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
This is a follow-on PR from #1726, which aimed to satisfy #631. Since that PR #2629 and #2639 have arisen; likely the same issue, or at least massively-overlapping.
The main changes in this PR include:
privacyplugin, which is only available to "Insiders". Without this change anyone wishing to build the Textual documentation for themselves would have to be a "Material for MkDocs Insider"..invfiles would result in an error when building the documentation while offline so this solves that.With #2629 in mind specifically: we may want to have a think about what "building from scratch" means and who we have in mind when we say this. For the Textualize team, with access the "Insiders", this should never be a problem as long as the correct "Material for MkDocs" setup is in place; if that's the case then
make docs-serveshould work out of the box.For people downloading the Textual source and wanting to build or work on the docs, they will need to use the
offlinetargets in theMakefile. At the moment this isn't especially obvious so as a subsequent bit of work to this PR, perhaps there's some things to think about:Meanwhile though, with this PR in place, as long as someone uses either
make docs-serve-offlineormake docs-build-offline, they should be able to work with the docs.NOTE: The privacy plugin was originally used to reduce the number of external resources used by the documentation (fonts and, I think, some stylesheets). With it removed those external resources of course remain external. This means that if someone builds the offline docs and then actually uses them offline, there will be a degraded experience, mainly relating to the fonts used in diagrams and screenshots.
Here's some examples of the offline docs being viewed without an Internet connection: