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.

Sign up for GitHub

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

fix: use consistent markup in examples #1373

Merged
merged 14 commits into from
Jul 3, 2023
Merged

fix: use consistent markup in examples #1373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
927cffa
fix: check the tab representation
12rambau Jul 2, 2023
834cf6c
fix: check the tab representation
12rambau Jul 2, 2023
8c785f6
correct setup for markdown files
12rambau Jul 2, 2023
de7d1dc
correct setup for markdown files
12rambau Jul 2, 2023
fdb9498
theme-element
12rambau Jul 2, 2023
ef6138f
docs: edit extending
12rambau Jul 2, 2023
bc35833
refactor: typo
12rambau Jul 2, 2023
ecdb5ed
docs: ligh-dark page
12rambau Jul 2, 2023
a5273b1
fix: static_assets
12rambau Jul 2, 2023
786acb8
use captions
12rambau Jul 2, 2023
21f373a
add metadata key
12rambau Jul 2, 2023
45ed5d2
typo
12rambau Jul 2, 2023
e2aa84b
typo
12rambau Jul 2, 2023
dbc9e61
fix: no need for raw in myst
12rambau Jul 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/community/topics/page-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,20 @@ This is [similar to how the TOML language defines nested configuration](https://

For example, to remove the secondary sidebar, we use a page metadata key like this:

`````{tab-set}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep this is the right way to do it. If you want to I believe that you can indent everything within the directive just to make it easier to read.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI indentation does not work (which is a shame because it does help readability of the source). It yields

  File "/opt/mambaforge/envs/pst/lib/python3.11/site-packages/sphinx_design/tabs.py", line 243, in run
    tab_label, tab_content = tab_item.children
    ^^^^^^^^^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 2, got 1)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that I get I think we can leave it as it is

````{tab-item} rst
```rst
:html_theme.sidebar_secondary.remove: true
```
````
````{tab-item} markdown
```md
---
html_theme.sidebar_secondary.remove: true
---
```
````
`````

Note how the period naturally separates nested sections, and looks very similar to what we'd expect if we put this in a Python dictionary in `conf.py`:

Expand Down
96 changes: 78 additions & 18 deletions docs/user_guide/extending.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,16 @@ Then add the ``dropdown`` class to any admonition directive (shown here on a ``n
:code: rst
:class: highlight-rst

.. tab-item:: markdown

.. code-block:: md

```{note}
:class: dropdown

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```


Custom admonition styles
========================
Expand Down Expand Up @@ -65,6 +75,14 @@ The title is specified on the same line as the ``.. admonition::`` directive:
:code: rst
:class: highlight-rst

.. tab-item:: markdown

.. code-block:: md

```{admonition} Custom title!

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

Styling with semantic color names
---------------------------------
Expand All @@ -90,6 +108,16 @@ Note that it updates both the color and the icon. See :doc:`./styling` for a lis
:code: rst
:class: highlight-rst

.. tab-item:: markdown

.. code-block:: md

```{admonition} Custom title with "warning" style
:class: warning

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

This theme defines classes for `the standard docutils admonition types <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`__ (``attention``, ``caution``, etc) and additionally supports ``seealso`` and ``todo`` admonitions (see :doc:`../examples/kitchen-sink/admonitions` for a demo of all built-in admonition styles).

Customizing the color
Expand Down Expand Up @@ -117,13 +145,23 @@ Be sure to use the same color for ``border-color`` and ``color`` and a different
:code: rst
:class: highlight-rst

.. tab-item:: css
.. tab-item:: markdown

.. code-block:: md

.. include:: ../_static/custom.css
:start-after: begin-custom-color
:end-before: /* end-custom-color
:code: css
:class: highlight-css
```{admonition} Admonition with custom "olive" color
:class: admonition-olive

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

And add the following to your ``custom.css`` file:

.. include:: ../_static/custom.css
:start-after: begin-custom-color
:end-before: /* end-custom-color
:code: css
:class: highlight-css


Using a custom icon
Expand All @@ -148,13 +186,23 @@ Customizing the icon uses a similar process to customizing the color: create a n
:code: rst
:class: highlight-rst

.. tab-item:: css
.. tab-item:: markdown

.. code-block:: md

```{admonition} Check out my custom icon
:class: admonition-icon

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

.. include:: ../_static/custom.css
:start-after: begin-custom-icon
:end-before: /* end-custom-icon
:code: css
:class: highlight-css
And add the following css to your ``custom.css`` file:

.. include:: ../_static/custom.css
:start-after: begin-custom-icon
:end-before: /* end-custom-icon
:code: css
:class: highlight-css


Combining all three customizations
Expand All @@ -179,10 +227,22 @@ Here we demonstrate an admonition with a custom icon, color, and title (and also
:code: rst
:class: highlight-rst

.. tab-item:: css
.. tab-item:: markdown

.. code-block:: md

````{admonition} YouTube
:class: dropdown admonition-youtube

```{youtube} dQw4w9WgXcQ
```

````

And add the following css to your custom.css file:

.. include:: ../_static/custom.css
:start-after: begin-custom-youtube
:end-before: /* end-custom-youtube
:code: css
:class: highlight-css
.. include:: ../_static/custom.css
:start-after: begin-custom-youtube
:end-before: /* end-custom-youtube
:code: css
:class: highlight-css
114 changes: 89 additions & 25 deletions docs/user_guide/light-dark.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,13 +86,29 @@ These are:
For example, the following page content defines two images, each of which uses a different one of the classes above.
Change the theme and a new image should be displayed.

.. code-block:: rst
.. tab-set::

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: only-dark
.. tab-item:: rst

.. image:: https://source.unsplash.com/200x200/daily?cute+dog
:class: only-light
.. code-block:: rst

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: only-dark

.. image:: https://source.unsplash.com/200x200/daily?cute+dog
:class: only-light

.. tab-item:: markdown

.. code-block:: md

```{image} https://source.unsplash.com/200x200/daily?cute+cat
:class: only-dark
```

```{image} https://source.unsplash.com/200x200/daily?cute+dog
:class: only-light
```

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: only-dark
Expand All @@ -115,20 +131,45 @@ theme-agnostic.
For example, here's an image without adding this helper class.
Change to the dark theme and a grey background will be present.

.. code-block:: rst
.. tab-set::

.. tab-item:: rst

.. code-block:: rst

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: p-2

.. tab-item:: markdown

.. code-block:: md

```{image} https://source.unsplash.com/200x200/daily?cute+cat
:class: p-2
```

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: p-2

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: p-2

Here's the same image with this class added:

.. code-block:: rst
.. tab-set::

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: dark-light p-2
.. tab-item:: rst

.. code-block:: rst

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: dark-light

.. tab-item:: markdown

.. code-block:: md

```{image} https://source.unsplash.com/200x200/daily?cute+cat
:class: dark-light p-2
```

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
:class: dark-light p-2
Expand All @@ -140,23 +181,46 @@ You can define a JavaScript event hook that will run your code any time the them
This is useful if you need to change elements of your page that cannot be defined by CSS rules.
For example, to change an image source (e.g., logo) whenever the ``data-theme`` changes, a snippet like this can be used:

.. code-block:: rst
.. tab-set::

.. tab-item:: rst

.. code-block:: rst

.. raw:: html

<script type="text/javascript">
var observer = new MutationObserver(function(mutations) {
const dark = document.documentElement.dataset.theme == 'dark';
document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
})
observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
</script>
<link rel="preload" href="_static/my_logo_dark.svg" as="image">

.. image:: _static/my_logo_light.svg
:alt: My Logo
:class: logo, mainlogo
:align: center

.. tab-item:: markdown

.. raw:: html
.. code-block:: md

<script type="text/javascript">
var observer = new MutationObserver(function(mutations) {
const dark = document.documentElement.dataset.theme == 'dark';
document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
})
observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
</script>
<link rel="preload" href="_static/my_logo_dark.svg" as="image">
<script type="text/javascript">
var observer = new MutationObserver(function(mutations) {
const dark = document.documentElement.dataset.theme == 'dark';
document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
})
observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
</script>
<link rel="preload" href="_static/my_logo_dark.svg" as="image">

.. image:: _static/my_logo_light.svg
:alt: My Logo
:class: logo, mainlogo
:align: center
```{image} _static/my_logo_light.svg
:alt: My Logo
:class: logo, mainlogo
:align: center
```

The JavaScript reacts to ``data-theme`` changes to alter ``img``, and the ``link`` is used to preload the dark image.
See the `MutationObserver documentation <https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver>`_ for more information.
21 changes: 11 additions & 10 deletions docs/user_guide/static_assets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,9 +103,11 @@ def setup(app):
## Add it directly to the page content

Finally, you can add CSS or JS directly to a page's content.
If you're using reStructuredText or MyST Markdown, you can use the `raw` directive:
If you're using either the raw directive (reStructuredText) or pure html (MyST Markdown).

```{code-block} rst
``````{tab-set}
`````{tab-item} rst
````{code-block} rst
:caption: some_page_in_my_site.rst
.. raw:: html

Expand All @@ -118,13 +120,10 @@ If you're using reStructuredText or MyST Markdown, you can use the `raw` directi
<script>
console.log("hi!")
</script>
```

If you're using MyST Markdown, you may also directly include any HTML / style / script blocks in your content without using a directive.

For example:

```{code-block} md
````
`````
`````{tab-item} markdown
````{code-block} md
:caption: other_page_in_my_site.md
# My title

Expand All @@ -140,4 +139,6 @@ Some text
## A bigger title

Some other text
```
````
`````
``````
Loading