From 571b703f1ccce0e768554adac82a1da95065bcad Mon Sep 17 00:00:00 2001 From: Kevin Zakka Date: Wed, 16 Nov 2022 10:23:13 -0800 Subject: [PATCH] Switch documentation to custom furo theme with dark mode option. Co-authored-by: Saran Tunyasuvunakool Co-authored-by: Yuval Tassa PiperOrigin-RevId: 488975449 Change-Id: Ia2db8ac7ecd27a00ca2c4c9ca5e85b9167813473 --- doc/XMLreference.rst | 29 ++++++---- doc/changelog.rst | 16 ++---- doc/conf.py | 47 +++++++++++++++- doc/css/theme_overrides.css | 109 ++++++++++++++++++++++++++---------- doc/images/banner.svg | 50 +++++++++++++++++ doc/requirements.txt | 3 +- 6 files changed, 199 insertions(+), 55 deletions(-) create mode 100644 doc/images/banner.svg diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index c08aa0c3..2d35e07b 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -13,17 +13,20 @@ XML schema ~~~~~~~~~~ The table below summarizes the XML elements and their attributes in MJCF. Note that all information in MJCF is entered -through elements and attributes. Text content in elements is not used; if present, the parser ignores it. The symbols -in the second column of the table have the following meaning: +through elements and attributes. Text content in elements is not used; if present, the parser ignores it. -====== =================================================== -**!** required element, can appear only once -**?** optional element, can appear only once -**\*** optional element, can appear many times -**R** optional element, can appear many times recursively -====== =================================================== +.. collapse:: Expand schema table -.. include:: XMLschema.rst + The symbols in the second column of the table have the following meaning: + + ====== =================================================== + **!** required element, can appear only once + **?** optional element, can appear only once + **\*** optional element, can appear many times + **R** optional element, can appear many times recursively + ====== =================================================== + + .. include:: XMLschema.rst .. _CType: @@ -33,7 +36,7 @@ Attribute types | Each attribute has a data type enforced by the parser. The available data types are: ========= ============================================================================================== -string    An arbitrary string, usually specifying a file name or a user-defined name of a model element. +string An arbitrary string, usually specifying a file name or a user-defined name of a model element. int(N) An array of N integers. If N is omitted it equals 1. real(N) An array of N real-valued numbers. If N is omitted it equals 1. [...] Keyword attribute. The list of valid keywords is given in brackets. @@ -50,7 +53,7 @@ real(N) An array of N real-valued numbers. If N is omitted it equals 1. compiler. When such attributes become relevant in a given context, they must be set to allowed values. +-------------+--------------------------------------------------------------------------------------------------+ -| required    | The attribute is required by the parser. If it is not present the parser will generate an error. | +| required | The attribute is required by the parser. If it is not present the parser will generate an error. | +-------------+--------------------------------------------------------------------------------------------------+ | optional | The attribute is optional. There is no internal default. The attribute is initialized in the | | | undefined state. | @@ -65,7 +68,9 @@ whose value can be "radian" or "degree". It is an optional attribute and has int will appear in the reference documentation as :at:`angle`: :at-val:`[radian, degree], "degree"` - |br| + .. raw:: html + +

.. _Reference: diff --git a/doc/changelog.rst b/doc/changelog.rst index e56af43b..a975b320 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -127,17 +127,11 @@ General between twist and anisotropy. - Added test using cantilever exact solution. -.. youtube:: 25kQP671fJE - :align: right - :height: 115px - -.. youtube:: 4DvGe-BodFU - :align: right - :height: 115px - -.. youtube:: QcGdpUd5H0c - :align: right - :height: 115px + +--------------------------+--------------------------+--------------------------+ + | .. youtube:: 25kQP671fJE | .. youtube:: 4DvGe-BodFU | .. youtube:: QcGdpUd5H0c | + | :align: center | :align: center | :align: center | + | :height: 140px | :height: 140px | :height: 140px | + +--------------------------+--------------------------+--------------------------+ Python bindings ^^^^^^^^^^^^^^^ diff --git a/doc/conf.py b/doc/conf.py index df19a737..49989547 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -45,6 +45,7 @@ extensions = [ 'sphinxcontrib.katex', 'sphinxcontrib.youtube', 'sphinx_reredirects', + 'sphinx_toolbox.collapse', ] # Add any paths that contain templates here, relative to this directory. @@ -79,7 +80,51 @@ autodoc_default_options = { # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +html_theme = 'furo' +html_title = 'MuJoCo Documentation' +html_logo = 'images/banner.svg' + +SHARED_CSS_VARIABLES = { + "admonition-font-size": "1rem", + "admonition-title-font-size": "1rem", + "sidebar-item-font-size": "115%", +} + +html_theme_options = { + "light_css_variables": { + "at-color": "#bc103e", + "at-val-color": "#bc103e", + "body-color": "#14234b", + "color-highlight-on-target": "#e5e8ed", + "primary-header-color": "#0053d6", + "row-odd-background-color": "#f0f3f7", + "rst-content-a-color": "#2980b9", + "secondary-header-color": "#123693", + "wy-menu-vertical-background-color": "#0053d6", + "wy-menu-vertical-color": "white", + "wy-nav-side-background-color": "#0053d6", + }, + "dark_css_variables": { + "at-color": "#ff95a6", + "at-val-color": "#ff95a6", + "body-color": "#14234b", + "color-admonition-background": "#1e1e21", + "color-highlight-on-target": "#3d4045", + "primary-header-color": "#a8caff", + "row-odd-background-color": "#222326", + "rst-content-a-color": "#2980b9", + "secondary-header-color": "#458dff", + "wy-menu-vertical-background-color": "#0053d6", + "wy-menu-vertical-color": "white", + "wy-nav-side-background-color": "#0053d6", + }, +} + +for v in html_theme_options.values(): + v.update(SHARED_CSS_VARIABLES) + +pygments_style = "default" +pygments_dark_style = "monokai" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/doc/css/theme_overrides.css b/doc/css/theme_overrides.css index e9c33d5b..0a4f0233 100644 --- a/doc/css/theme_overrides.css +++ b/doc/css/theme_overrides.css @@ -1,37 +1,48 @@ @import url('https://fonts.googleapis.com/css2?family=DM+Sans:ital,wght@0,400;0,500;0,700;1,400;1,500;1,700&display=swap'); -@import url('https://fonts.googleapis.com/css2?family=DM+Serif+Text:ital,wght@0,400;1,400&display=swap'); -@import url('https://fonts.googleapis.com/css2?family=DM+Serif+Display:ital,wght@0,400;1,400&display=swap'); -@import url('https://fonts.googleapis.com/css2?family=DM+Mono:ital,wght@0,400;0,500;1,400;1,500&display=swap'); + +/* Disable scroll on anchor. */ +html { + scroll-behavior: auto; +} body { font-family: 'DM Sans', 'Helvetica Neue', 'Arial', sans-serif; -webkit-font-smoothing: antialiased; - color: rgb(20, 35, 75); + color: var(--body-color); } -.rst-content .toctree-wrapper>p.caption,h1 { - font-size: 250%; - font-family: 'DM Serif Display', 'Times New Roman', serif; - font-weight: 400; - color: rgb(0, 83, 214); +.sidebar-brand-text { + display: none; } -.rst-content .toctree-wrapper>p.caption,h2,h3,h4,h5,h6,legend { +h1 { + font-size: 300%; + font-family: 'DM Sans', 'Helvetica Neue', 'Arial', sans-serif; + font-weight: 600; + color: var(--primary-header-color); + margin-top: 1em; +} + +h2,h3,h4,h5,h6,legend { font-family: 'DM Sans', 'Helvetica Neue', 'Arial', sans-serif; -webkit-font-smoothing: antialiased; font-weight: 700; - color: rgb(18, 54, 147); + color: var(--secondary-header-color); } -/* Decrease bottom margin of some headings for tighter vertical spacing. */ -.rst-content h2 { - margin-bottom: 20px; +h2 { + margin-top: 1.2em; + margin-bottom: 0.75em; } -.rst-content h3 { - margin-bottom: 10px; + +h3 { + margin-top: 0.75em; + margin-bottom: 0.5em; } -.rst-content h4 { - margin-bottom: 5px; + +h4 { + margin-top: 0.5em; + margin-bottom: 0.25em; } /* Paragraph margins don't apply to table cell contents. */ @@ -44,10 +55,10 @@ body { padding: 6px; } -/* Don't change color of visited links. */ +/* Don't change color of visited links. .rst-content a.reference:visited { - color: #2980b9; -} + color: var(--rst-content-a-color); +} */ .rst-content code, .rst-content tt { font-size: 90%; @@ -63,17 +74,24 @@ body { ul.simple { list-style: disc; margin-left: 24px; + margin-top: 0.5em; + margin-bottom: 0.5em; } ul.simple li { list-style: disc; } +ol { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + /* Change background color of the nav bars. */ .wy-side-nav-search, .wy-nav-top, .wy-nav-side { - background-color: rgb(0, 83, 214); + background-color: var(--wy-nav-side-background-color); } /* Make text wrap in table cells. */ @@ -121,7 +139,7 @@ html.writer-html5 .rst-content table.docutils th>p { .wy-menu-vertical li.toctree-l8 a:hover span.toctree-expand, .wy-menu-vertical li.toctree-l9 a:hover span.toctree-expand, .wy-menu-vertical li.toctree-l10 a:hover span.toctree-expand { - color: white; + color: var(--wy-menu-vertical-color); } /* Change color of TOC background. */ @@ -139,30 +157,49 @@ html.writer-html5 .rst-content table.docutils th>p { .wy-menu-vertical li.toctree-l7.current li.toctree-l8>a, .wy-menu-vertical li.toctree-l8.current li.toctree-l9>a, .wy-menu-vertical li.toctree-l9.current li.toctree-l10>a { - background-color: rgb(0, 83, 214); + background-color: var(--wy-menu-vertical-background-color); border: none; } +/* Alternate row colors. */ +table.docutils:not(.mjcf-attributes) > tbody > tr.row-odd { + background-color: var(--row-odd-background-color); +} + /* MJCF attributes table. */ -.rst-content table.mjcf-attributes { +table.mjcf-attributes { border-style: none; margin-left: 0px; margin-right: 0px; width: 100%; + box-shadow: none; } -.rst-content table.mjcf-attributes:not(.field-list) tr td, -.rst-content table.mjcf-attributes:not(.field-list) tr:nth-child(2n-1) td { +table.mjcf-attributes tbody tr td, +table.mjcf-attributes tbody tr:nth-child(2n-1) td { border-style: none; - background-color: rgba(255, 255, 255, 0); padding: 0px 0px 0px 0px; width: 33%; } +table.mjcf-attributes tbody tr td p { + margin: 0; +} + +div.table-wrapper.mjcf-attributes { + margin: 0.5em; + padding: 0; +} + table td > div.wy-table-responsive { margin-bottom: 0px; } +/* Remove vertical spacing before/after code blocks. */ +div[class*=" highlight-"], div[class^=highlight-] { + margin: 0; +} + /* MJCF element names. */ .el { font-weight: bold; @@ -170,12 +207,16 @@ table td > div.wy-table-responsive { /* MJCF attribute names. */ .at { - color: darkred; + color: var(--at-color); +} + +dt .at { + font-weight: 600; } /* MJCF attribute value specs. */ .at-val { - color: darkred; + color: var(--at-val-color); font-weight: normal; } @@ -183,3 +224,11 @@ table td > div.wy-table-responsive { .toctree-l1 .el-prefix { display: none; } + +.admonition p:not(.admonition-title) { + margin-left: 0.5em; +} + +details summary { + font-weight: 600; +} diff --git a/doc/images/banner.svg b/doc/images/banner.svg new file mode 100644 index 00000000..995935cb --- /dev/null +++ b/doc/images/banner.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/requirements.txt b/doc/requirements.txt index b8228eba..537fb04c 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,8 +1,9 @@ Sphinx==4.5.0 -sphinx-rtd-theme==1.0.0 +furo==2022.9.29 sphinxcontrib-katex==0.8.6 sphinxcontrib-youtube==1.1.0 sphinx-reredirects==0.0.1 +sphinx-toolbox==3.2.0 nbsphinx==0.8.0 pandoc==1.0.2 pygments==2.7.4