Skip to content
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
merged 6 commits into from May 14, 2019

Conversation

jugglinmike
Copy link
Contributor

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).

jugglinmike and others added 6 commits May 14, 2019 14:49
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'
Copy link
Member

@gsnedders gsnedders left a 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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants