From 8c2c0916eb43705433d05e3566a696a4d8dad06e Mon Sep 17 00:00:00 2001 From: Mandeep Singh Baines Date: Wed, 9 Sep 2020 16:53:48 -0700 Subject: [PATCH] [docs] use PyTorch Sphinx theme --- .isort.cfg | 2 +- docs/source/_static/css/customize.css | 11 + docs/source/_templates/layout.html | 364 +++++++++++++++++++ docs/source/_templates/theme_variables.jinja | 16 + docs/source/conf.py | 38 +- 5 files changed, 426 insertions(+), 5 deletions(-) create mode 100644 docs/source/_static/css/customize.css create mode 100644 docs/source/_templates/layout.html create mode 100644 docs/source/_templates/theme_variables.jinja diff --git a/.isort.cfg b/.isort.cfg index 158acd6e2..4a682ea8f 100644 --- a/.isort.cfg +++ b/.isort.cfg @@ -1,2 +1,2 @@ [settings] -known_third_party =numpy,pytest,setuptools,torch,torchtext,torchvision +known_third_party =numpy,pytest,pytorch_sphinx_theme,recommonmark,setuptools,torch,torchtext,torchvision diff --git a/docs/source/_static/css/customize.css b/docs/source/_static/css/customize.css new file mode 100644 index 000000000..3b39e3ac9 --- /dev/null +++ b/docs/source/_static/css/customize.css @@ -0,0 +1,11 @@ +.tutorials-header .header-logo { + background-image: url("../images/fairscale-logo-dark.svg"); +} + +.header-logo { + background-image: url("../images/fairscale-logo.svg"); +} + +.footer-logo { + background-image: url("../images/fairscale-logo-icon.svg"); +} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 000000000..aba6dda80 --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,364 @@ +{# TEMPLATE VAR SETTINGS #} +{%- set url_root = pathto('', 1) %} +{%- if url_root == '#' %}{% set url_root = '' %}{% endif %} +{%- if not embedded and docstitle %} + {%- set titlesuffix = " | "|safe + docstitle|e %} +{%- else %} + {%- set titlesuffix = "" %} +{%- endif %} +{%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %} +{% import 'theme_variables.jinja' as theme_variables %} + + + + + + + {{ metatags }} + + {% block htmltitle %} + {{ title|striptags|e }}{{ titlesuffix }} + {% endblock %} + + + {# FAVICON #} + + {# CANONICAL URL #} + {% if theme_canonical_url %} + + {% endif %} + + + + + + + + {# CSS #} + + {# OPENSEARCH #} + {% if not embedded %} + {% if use_opensearch %} + + {% endif %} + + {% endif %} + + + + {%- for css in css_files %} + {%- if css|attr("rel") %} + + {%- else %} + + {%- endif %} + {%- endfor %} + {%- for cssfile in extra_css_files %} + + {%- endfor %} + + {%- block linktags %} + {%- if hasdoc('about') %} + + {%- endif %} + {%- if hasdoc('genindex') %} + + {%- endif %} + {%- if hasdoc('search') %} + + {%- endif %} + {%- if hasdoc('copyright') %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} + {%- endblock %} + {%- block extrahead %} {% endblock %} + + {# Keep modernizr in head - http://modernizr.com/docs/#installing #} + + + {% include "fonts.html" %} + + +
+
+
+ + +
+ +
+ + +
+ +
+
+ + + + + {% block extrabody %} {% endblock %} + + {# SIDE NAV, TOGGLES ON MOBILE #} + +
+ Table of Contents + +
+ + + +
+
+
+ {% include "breadcrumbs.html" %} +
+ +
+ Shortcuts +
+
+ +
+
+ + {% if theme_pytorch_project == 'tutorials' %} + +
+
{{ pagename }}
+ + + + +
+ + {% endif %} + + {%- block content %} + {% if theme_style_external_links|tobool %} +
+ {% else %} +
+ {% endif %} +
+ {%- block document %} +
+ {% block body %}{% endblock %} +
+ {% if self.comments()|trim %} +
+ {% block comments %}{% endblock %} +
+ {% endif%} +
+ {%- endblock %} + {% include "footer.html" %} +
+ {%- endblock %} +
+ +
+
+
+ {{ toc }} +
+
+
+
+
+ + {% include "versions.html" %} + + {% if not embedded %} + + {% if sphinx_version >= "1.8.0" %} + + {%- for scriptfile in script_files %} + {{ js_tag(scriptfile) }} + {%- endfor %} + {% else %} + + {%- for scriptfile in script_files %} + + {%- endfor %} + {% endif %} + + {% endif %} + + + + + + + + + {%- block footer %} {% endblock %} + + + + + + + {% include "cookie_banner.html" %} + + + + + +
+
+
+
+ + +
+
+
+ +
+
+ +
+
+
+ + + + + + + + diff --git a/docs/source/_templates/theme_variables.jinja b/docs/source/_templates/theme_variables.jinja new file mode 100644 index 000000000..19f7c1f71 --- /dev/null +++ b/docs/source/_templates/theme_variables.jinja @@ -0,0 +1,16 @@ +{%- +set external_urls = { + 'github': 'https://github.com/facebookresearch/fairscale', + 'github_issues': 'https://github.com/facebookresearch/fairscale/issues', + 'contributing': 'https://github.com/facebookresearch/fairscale/blob/master/CONTRIBUTING.md', + 'docs': 'https://fairscale.readthedocs.io/', + 'home': 'https://fairscale.readthedocs.io/', + 'get_started': 'https://github.com/facebookresearch/fairscale/blob/master/README.md', + 'brand_guidelines': 'https://pytorch.org/assets/brand-guidelines/PyTorch-Brand-Guidelines.pdf' +} +-%} +{%- +set og = { + 'description': 'API docs for fairscale. fairscale is a PyTorch extension library for high performance and large scale training.' +} +-%} diff --git a/docs/source/conf.py b/docs/source/conf.py index 950f5adf9..80318fed4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,6 +13,13 @@ import os import sys +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# At the bottom of conf.py +import pytorch_sphinx_theme +from recommonmark.transform import AutoStructify + sys.path.insert(0, os.path.abspath("../..")) # -- Project information ----------------------------------------------------- @@ -45,12 +52,35 @@ # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "alabaster" + +html_theme = "pytorch_sphinx_theme" +html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()] +templates_path = ["_templates"] # Add any paths that contain custom static files (such as style sheets) here, +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + "includehidden": False, + "canonical_url": "https://mmf.sh/api/", + "pytorch_project": "docs", +} + # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] + +# Over-ride PyTorch Sphinx css +def setup(app): + app.add_config_value( + "recommonmark_config", + { + "url_resolver": lambda url: github_doc_root + url, + "auto_toc_tree_section": "Contents", + }, + True, + ) + app.add_transform(AutoStructify) + app.add_css_file("css/customize.css")