New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[docs] Re-implement website build process #16822
Merged
gsnedders
merged 6 commits into
web-platform-tests:master
from
bocoup:docs-sphinx-3-reland
May 14, 2019
Merged
[docs] Re-implement website build process #16822
gsnedders
merged 6 commits into
web-platform-tests:master
from
bocoup:docs-sphinx-3-reland
May 14, 2019
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
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown.
Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g'
gsnedders
approved these changes
May 14, 2019
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's try this again.
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.
This pull request is identical to gh-16458, which was reverted following an erroneous deployment. @jgraham and I have configured this repository with the necessary information (that is: a GitHub "secret" named
DEPLOY_TOKEN
), so we expect it to function as intended now (as demonstrated by the wpt-actions-test repository).