Sphinx theme for PyTorch Docs and PyTorch Tutorials based on the Read the Docs Sphinx Theme.
Run python setup:
git clone https://github.com/pytorch/pytorch_sphinx_theme
pip install -e pytorch_sphinx_theme
and install the dependencies using pip install -r docs/requirements.txt
In the root directory install the package.json
:
# node version 8.4.0
yarn install
If you have npm
installed then run:
npm install
docs/demo
then create.env.json
file and make it empty json file. Means .env.json file
will{}
Run grunt to build the html site and enable live reloading of the demo app at localhost:1919
:
grunt
.env.json
{
"DOCS_DIR": "docs/",
"TUTORIALS_DIR": "path/to/tutorial/directory"
}
Run grunt to build the html site for docs:
grunt --project=docs
and to build the html site for tutorial:
grunt --project=tutorials
The resulting site is a demo.
When you are ready to submit a PR with your changes you can first test that your changes have been applied correctly against either the PyTorch Docs or Tutorials repo:
grunt build
task on your branch and commit the build to Github.pytorch_sphinx_theme
packages in the src
folder (there should be a pip-delete-this-directory.txt
file there)git clone https://github.com/pytorch/pytorch_sphinx_theme
pytorch_sphinx_theme
by running pip install -e pytorch_sphinx_theme
pip install -r requirements.txt
make clean
, tutorials is make clean-cache
make html
, tutorials is make html-noplot
docs/build/html/index.html
, in the tutorials open _build/html.index.html
If your changes have been applied successfully, remove the build commit from your branch and submit your PR.
Before the new changes are visible in the theme the maintainer will need to run the build process:
grunt build
Once that is successful commit the change to Github.
To be able to modify and preview the theme locally against the PyTorch Docs and/or the PyTorch Tutorials first clone the repositories:
Then follow the instructions in each repository to make the docs.
Once the docs have been successfully generated you should be able to run the following to create an html build.
# in ./docs
make html
# root directory
make html
Once these are successful, navigate to the conf.py
file in each project. In the Docs these are at ./docs/source
. The Tutorials one can be found in the root directory.
In conf.py
change the html theme to pytorch_sphinx_theme
and point the html theme path to this repo's local folder, which will end up looking something like:
html_theme = 'pytorch_sphinx_theme'
html_theme_path = ["../../../pytorch_sphinx_theme"]
Next create a file .env.json
in the root of this repo with some keys/values referencing the local folders of the Docs and Tutorials repos:
{
"TUTORIALS_DIR": "../tutorials",
"DOCS_DIR": "../pytorch/docs/source"
}
You can then build the Docs or Tutorials by running
grunt --project=docs
or
grunt --project=tutorials
These will generate a live-reloaded local build for the respective projects available at localhost:1919
.
Note that while live reloading works these two projects are hefty and will take a few seconds to build and reload, especially the Docs.
There are a couple of stylesheets and fonts inside the Docs and Tutorials repos themselves meant to override the existing theme. To ensure the most accurate styles we should comment out those files until the maintainers of those repos remove them:
# ./docs/source/conf.py
html_context = {
# 'css_files': [
# 'https://fonts.googleapis.com/css?family=Lato',
# '_static/css/pytorch_theme.css'
# ],
}
# ./conf.py
# app.add_stylesheet('css/pytorch_theme.css')
# app.add_stylesheet('https://fonts.googleapis.com/css?family=Lato')
The top navigation and mobile menu expect an "active" state for one of the menu items. To ensure that either "Docs" or "Tutorials" is marked as active, set the following config value in the respective conf.py
, where {project}
is either "docs"
or "tutorials"
.
html_theme_options = {
...
'pytorch_project': {project}
...
}