Add smv_build_targets option to configure multiple build targets #74
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
Add smv_build_targets configuration option. This will allow users to specify an arbitrary number of build targets to build for each version of the documentation, and specify whether it should be available to documentation consumers to download. This supports all sphinx builders, and output formats where there is a single output file. For build targets where there are multiple output files (such as html), all archive formats supported by shutil.make_archive are supported. Downloadable build targets are placed in an `artefacts/` directory within each versions build directory. Add smv_clean_intermediate_files configuration option. This will allow users to determine whether the intermediate files are removed or not. This is a useful configuration option where the generated build artefacts are not for public download consumption. Reorder build arguments passed to `sphinx` such that the source and build directory are the first two arguments. This is to ensure that there is compatability between the `-M` and `-b` sphinx build flags, which have slightly different APIs.
Add apathto method to discover artefact paths. Add dictionary comprehension to pair build target names and artefact paths to each version object. This will ensure that the build artefacts for the current build is accessible via the current_version key in html_context. Add modifier to replace slashes in branch names with hyphens for file naming purposes. This will ensure that the file name is not split and a truncated version used for the artefact name. Add shutil.py as a third party library to ensure backwards compatability can be achieved with python 3.6. shutil.copytree only accepts the dir_exists_ok argument from python 3.8. Add unit tests and update metadata schema with appropriate mocked objects for app configuration.
Add documentation detailing appropriate configuration of the smv_build_targets configuration setting including exemplars to illustrate the features and also limitations of this feature. Add documentation detailing appropriate configuration of the smv_clean_intermediate_files configuration setting. Add exemplar usage of the new artefacts object in the html context within template files. Closes sphinx-contrib#70.
|
I've noticed that the Travis CI tests you have set up are for Python 3.6 and 3.7. I've utilised the |
Add file matching that accounts for project names that include spaces and is case insensitive. This is to match how latex and other builders generate their artefacts. Use only the project name from the build configuration rather than the configuration on each branch to account for when the project name has been changed to display differently.
Refactored pattern matching to only match patterns when there's more than one result. When there's one result, this is assumed to be the build artefact, which should provide some flexibility for artefact recognition without sacrificing quality. This also opens the door for future filtering based on user specified patterns.
Trying to access a download artefact from a page other than the root would fail to resolve the correct artefact path. This change adds support to resolve the correct path from any page the user is located on. Add unit tests to confirm this feature works as expected, and also to ensure artefacts are found correctly when the project name contains spaces and variable casing.
samuel-emrys
force-pushed
the
feature/70-alternate-build-targets
branch
from
02b4f7b
to
cd72335
Compare
|
@Holzhaus is there anything I can do to get this merged in? |
|
Hello, @samuel-emrys Thanks for the PR, I find the feature really useful and easy to use. I have tested it and I found one issue, I'm sending a review to the PR. @Holzhaus or other manager of this repository, please can you review and merge this PR? |
numero-744
reviewed
Oct 26, 2022
…l context * Add feature to ensure that build targets with downloadable=False don't populate the artifacts html context. This fixes a bug in which setting downloadable=False would provide a download link with the provided HTML jinja templates. Setting downloadable=False will now no longer result in a download link being made available.
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.
I thought it would be useful to be able to bring functionality closer to what readthedocs offers in terms of downloadable documentation for each version documentation is produced for. The
smv_build_targetsconfiguration option will allow a user to specify the formats in which the documentation should be provided for download, along with more granular control of the sphinx builder used to generate this documentation.This PR also introduces the
smv_clean_intermediate_filesconfiguration option, which allows a user to have control over whether the intermediate build directories are removed after building the documentation. This defaults toTrue, however this would allow users who wish to manipulate build files with another program/script to do so if required.Review and any comments/suggestions welcome.
Closes #70.