Package: tu-sphinx-theme
IntroductionThis theme is adapted from PyTorch Sphinx Theme, with more configurations allowed.Used onhttps://torch-uncertainty.github.io/forTorchUncertainty.Getting StartedAdd dependencies torequirements.txt,-e git+https://github.com/open-mmlab/tu_sphinx_theme.git#egg=tu_sphinx_theme
sphinx_copybuttonIndocs/conf.py:importtu_sphinx_themehtml_theme='tu_sphinx_theme'html_theme_path=[tu_sphinx_theme.get_html_theme_path()]# Ignore >>> when copying codecopybutton_prompt_text=r'>>> |\.\.\. 'copybutton_prompt_is_regexp=TrueHeader LogoThe header logo is OpenMMLab by default. Each repo should customize the logo by overriding the provided css class.We suggest putting all the html resources todocs/_static. First put the logo
todocs/_static/images/logo.png, then write the following snippet todocs/_static/css/readthedocs.css:.header-logo{background-image:url("../images/logo.png");background-size:110px40px;height:40px;width:110px;}Here, you are recommended to fix the height to40pxand scale the width according to the logo's aspect ratio.
The latest thing to do is to tell Sphinx the location of these resources by adding the following lines todocs/conf.py:html_static_path=['_static']html_css_files=['css/readthedocs.css']Header CustomizationThis theme variant also allows users to customize the header, such as the logo url and the navigation menu, in a pythonic way. They are all configurable options inhtml_theme_optionsindocs/conf.py.Here is an example config covering all available options:html_theme_options={# The target url that the logo directs to. Unset to do nothing'logo_url':'https://mmocr.readthedocs.io/en/latest/',# "menu" is a list of dictionaries where you can specify the content and the# behavior of each item in the menu. Each item can either be a link or a# dropdown menu containing a list of links.'menu':[# A link{'name':'GitHub','url':'https://github.com/open-mmlab/'},# A dropdown menu{'name':'Projects','children':[# A vanilla dropdown item{'name':'MMCV','url':'https://github.com/open-mmlab/mmcv',},# A dropdown item with a description{'name':'MMDetection','url':'https://github.com/open-mmlab/mmdetection','description':'Object detection toolbox and benchmark'},],# Optional, determining whether this dropdown menu will always be# highlighted.'active':True,},],# For shared menu: If your project is a part of OpenMMLab's project and# you would like to append Docs and OpenMMLab section to the right# of the menu, you can specify menu_lang to choose the language of# shared contents. Available options are 'en' and 'cn'. Any other# strings will fall back to 'en'.'menu_lang':'en',}PyTorch Sphinx ThemeSphinx theme forPyTorch DocsandPyTorch Tutorialsbased on theRead the Docs Sphinx Theme.Local DevelopmentRun python setup:python setup.py installand install the dependencies usingpip install -r docs/requirements.txtIn the root directory install thepackage.json:# node version 8.4.0
yarn installIf you havenpminstalled then run:npm installIf you want to see generated documentation fordocs/demothen create.env.jsonfile and make it empty json file. Means.env.json filewill
contain{}Run grunt to build the html site and enable live reloading of the demo app atlocalhost:1919:gruntIf you want to specify the project folder (docs or tutorial for which
you want to see docs generated) then you need to specify it into.env.jsonfile:{
    "DOCS_DIR": "docs/",
    "TUTORIALS_DIR": "path/to/tutorial/directory"
}Run grunt to build the html site for docs:grunt --project=docsand to build the html site for tutorial:grunt --project=tutorialsThe resulting site is a demo.Testing your changes and submitting a PRWhen 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:Run thegrunt buildtask on your branch and commit the build to Github.In your local docs or tutorials repo, remove any existingtu_sphinx_themepackages in thesrcfolder (there should be apip-delete-this-directory.txtfile there)Inrequirements.txtreplace the existing git link with a link pointing to your commit or branch, e.g.-e git+git://github.com/{ your repo }/tu_sphinx_theme.git@{ your commit hash }#egg=tu_sphinx_themeInstall the requirementspip install -r requirements.txtRemove the current build. In the docs this ismake clean, tutorials ismake clean-cacheBuild the static site. In the docs this ismake html, tutorials ismake html-noplotOpen the site and look around. In the docs opendocs/build/html/index.html, in the tutorials open_build/html.index.htmlIf your changes have been applied successfully, remove the build commit from your branch and submit your PR.Publishing the themeBefore the new changes are visible in the theme the maintainer will need to run the build process:grunt buildOnce that is successful commit the change to Github.Developing locally against PyTorch Docs and TutorialsTo be able to modify and preview the theme locally against the PyTorch Docs and/or the PyTorch Tutorials first clone the repositories:PyTorch (Docs)PyTorch TutorialsThen 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.Docs# in ./docs
make htmlTutorials# root directory
make htmlOnce these are successful, navigate to theconf.pyfile in each project. In the Docs these are at./docs/source. The Tutorials one can be found in the root directory.Inconf.pychange the html theme totu_sphinx_themeand point the html theme path to this repo's local folder, which will end up looking something like:html_theme = 'tu_sphinx_theme'
html_theme_path = ["../../../tu_sphinx_theme"]Next create a file.env.jsonin 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 runninggrunt --project=docsorgrunt --project=tutorialsThese will generate a live-reloaded local build for the respective projects available atlocalhost: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.Built-in Stylesheets and FontsThere 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# ./docs/source/conf.py

html_context = {
    # 'css_files': [
    #     'https://fonts.googleapis.com/css?family=Lato',
    #     '_static/css/pytorch_theme.css'
    # ],
}Tutorials# ./conf.py

# app.add_stylesheet('css/pytorch_theme.css')
# app.add_stylesheet('https://fonts.googleapis.com/css?family=Lato')Top/Mobile NavigationThe 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 respectiveconf.py, where{project}is either"docs"or"tutorials".html_theme_options = {
  ...
  'pytorch_project': {project}
  ...
}