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

Jump to bottom

DOCS: Refactor demo docs #544

Merged
merged 11 commits into from Jan 14, 2022
Merged

DOCS: Refactor demo docs #544

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
068f20d
DOCS: Refactor demo docs
choldgraf Jan 9, 2022
d9176ea
Add check for sphinx warnings
choldgraf Jan 10, 2022
60bd137
Add ref page for no sideabr
choldgraf Jan 10, 2022
03e7ab4
Remove unnecessary rebuild from github action
choldgraf Jan 10, 2022
82c73d3
Fix artifact
choldgraf Jan 10, 2022
f913d22
Add audit dependency w/ tests
choldgraf Jan 10, 2022
f1efbd1
Revert workflow test
choldgraf Jan 10, 2022
dfa163e
Fixing lighthouse audit file paths
choldgraf Jan 10, 2022
63aef32
Add extra rule to roadmap
choldgraf Jan 10, 2022
b45f9bc
Merge from master
choldgraf Jan 11, 2022
376cc5c
Clean up kitchen sink docs
choldgraf Jan 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
30 changes: 14 additions & 16 deletions .github/workflows/tests.yml
View file
Open in desktop
Expand Up @@ -52,7 +52,17 @@ jobs:
# Build the docs
- name: Build docs to store
run: |
sphinx-build -b html docs/ docs/_build/html -W --keep-going
sphinx-build -b html docs/ docs/_build/html --keep-going -w warnings.txt

- name: Check that there are no unexpected Sphinx warnings
if: matrix.python-version == '3.9'
shell: python
run: |
from pathlib import Path
text = Path("./warnings.txt").read_text().strip()
print("\n=== Sphinx Warnings ===\n\n" + text) # Print just for reference so we can look at the logs
unexpected = [ii for ii in text.split("\n") if "kitchen-sink" not in ii]
assert len(unexpected) == 0
Copy link
Member

Choose a reason for hiding this comment

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

The reason for this manual check instead of -W is to not error on warnings in the kitchen sink pages? (since those are out of our control?)

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

The manual check is because we know the kitchen sink has errors, and that is because we want to be able to demo what it looks like when an error is rendered into the actual page, since many of our users will do this. So we want to make sure that there are no "unexpected errors", which is what this check is for

Copy link
Member

Choose a reason for hiding this comment

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

OK, great!


# Run tests under coverage
- name: Run the tests
Expand Down Expand Up @@ -86,28 +96,15 @@ jobs:
cache: "pip"
cache-dependency-path: "pyproject.toml"

- name: Set up Node/yarn
uses: actions/setup-node@v1
with:
node-version: "16.x"

- name: Cache node_modules
uses: actions/cache@v2
with:
path: "node_modules"
key: |
${{ runner.os }}-node-modules-${{ hashFiles('package.json') }}

- name: Install dependencies
run: |
python -m pip install --upgrade pip wheel setuptools
python -m pip install -e .[coverage]
yarn --frozen-lockfile

# Build the docs
- name: Build docs to store
run: |
sphinx-build -b html docs/ docs/_build/html -W --keep-going
sphinx-build -b html docs/ docs/_build/html
jorisvandenbossche marked this conversation as resolved.
Show resolved Hide resolved

# Serve the docs and wait to be ready
- name: Serve the built site
Expand All @@ -128,7 +125,8 @@ jobs:
urls: >-
${{ env.URL }}/index.html,
${{ env.URL }}/demo/api.html,
${{ env.URL }}/demo/demo.html,
${{ env.URL }}/demo/kitchen-sink/paragraph-markup.html,
${{ env.URL }}/demo/kitchen-sink/lists-and-tables.html,
${{ env.URL }}/demo/example_pandas.html,
${{ env.URL }}/user_guide/accessibility.html
outputDirectory: /tmp/lighthouse/lighthouse-${{ github.run_number }}
Expand Down
1 change: 1 addition & 0 deletions docs/conf.py
View file
Open in desktop
Expand Up @@ -120,6 +120,7 @@
"sidebar-nav-bs",
"custom-template",
], # This ensures we test for custom sidebars
"demo/no-sidebar": [], # Test what page looks like with no sidebar items
}


Expand Down
19 changes: 19 additions & 0 deletions docs/contribute/topics.md
View file
Open in desktop
Expand Up @@ -223,3 +223,22 @@ is required. The steps are roughly:
- remove references to the font being replaced/removed, if applicable
- see the `font-awesome` sections of this configuration to see what the end-result configuration looks like.
- re-compile the theme's assets: `nox -s compile`

## Update our kitchen sink documents

The [kitchen sink reference](../demo/kitchen-sink/index.rst) is for demonstrating as much syntax and style for Sphinx builds as possible.
It is copied directly from the [`sphinx-themes.org` documentation](https://sphinx-themes.org/) so that we use standardized reference docs compared with other communities.
The source files for these pages are stored [in the `sphinx-themes.org` repository](https://github.com/sphinx-themes/sphinx-themes.org/raw/master/sample-docs/kitchen-sink/).

If you'd like to update our local files with any changes that have been made to the `sphinx-themes.org` files, simply copy/paste those changes into our local files and make a commit.

Here's a list of our pages and where they come from in `sphinx-themes.org`:

- [`index.rst`](../demo/kitchen-sink/index.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/index.rst))
- [`api.rst`](../demo/kitchen-sink/api.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/api.rst))
- [`lists-and-tables.rst`](../demo/kitchen-sink/lists-and-tables.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/lists-and-tables.rst))
- [`paragraph-markup.rst`](../demo/kitchen-sink/paragraph-markup.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/paragraph-markup.rst))

:::{note}
To demonstrate extra styles and syntax that is not in the Kitchen sink, use the [Theme Elements reference](../demo/theme-elements.md).
:::
6 changes: 3 additions & 3 deletions docs/demo/api.rst
View file
Open in desktop
@@ -1,6 +1,6 @@
***************************************
API documentation and generated content
***************************************
************************************************
Advanced API documentation and generated content
************************************************

This page contains general code elements that are common
for package documentation.
Expand Down
16 changes: 6 additions & 10 deletions docs/demo/index.rst
View file
Open in desktop
Expand Up @@ -10,24 +10,20 @@ the left sidebar to see how various elements look on this theme.
:maxdepth: 2
:caption: Demo Documentation

structure
demo
kitchen-sink/index
theme-elements
api
lists_tables
markdown
example_pandas
mult_headers
subpages/index
subpages2/index
Copy link
Member

Choose a reason for hiding this comment

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

For some reason I added two collapsible pages next to each other in #349 (the subpages2 in addition to subpages), but I don't remember if that had a practical reason for testing .. (I suppose we can always add it back when we discover something related to it)

Link to an external site <https://jupyterbook.org/>

.. toctree::
:maxdepth: 3
:numbered:
:caption: This is an incredibly long caption for a long menu

long
:caption: This is an incredibly long caption for a long menu. Here are some more subpages to show off deep nested pages.

no-sidebar
mult_headers
subpages/index

.. meta::
:description lang=en:
Expand Down
10 changes: 10 additions & 0 deletions docs/demo/kitchen-sink/api.rst
View file
Open in desktop
@@ -0,0 +1,10 @@
.. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT
*****************
API documentation
*****************

``asyncio``
===========

.. automodule:: asyncio
:members: run, gather, AbstractEventLoop
12 changes: 12 additions & 0 deletions docs/demo/kitchen-sink/index.rst
View file
Open in desktop
@@ -0,0 +1,12 @@
.. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT
============
Kitchen Sink
============

This section showcases the various elements that Sphinx supports out-of-the-box.

.. toctree::

paragraph-markup
api
lists-and-tables
66 changes: 54 additions & 12 deletions docs/demo/lists_tables.rst → docs/demo/kitchen-sink/lists-and-tables.rst
View file
Open in desktop
@@ -1,4 +1,4 @@

.. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT
**************
Lists & Tables
**************
Expand Down Expand Up @@ -47,6 +47,18 @@ Term : classifier
Term
Definition

I have no clue why the definition list below is classified as a different style
of definition list than the one above.

Is it the spaces in the term?
Maybe it was the multiple line paragraph
in the line below that caused this?

Is it the paragraph above the list maybe?
I guess a lot of these lists don't have leading paragraphs?

Is it everything all at once?
Who knows?!

Option Lists
------------
Expand Down Expand Up @@ -116,6 +128,28 @@ Field list
Bullet Lists
------------

..
Docutils supports two types of lists, "simple" and "complex". Complex lists
have item margins, simple lists do not.
https://docutils.sourceforge.io/sandbox/html4strict/data/simple-lists.html

Simple
^^^^^^

- A simple list.
- There are no margins between list items.
- Simple lists do not contain multiple paragraphs. That's a complex list.
- In the case of a nested list

- There are no margins between elements

- Still no margins

- Still no margins

Complex
^^^^^^^

- A bullet list

+ Nested bullet list.
Expand All @@ -136,6 +170,13 @@ Bullet Lists
- ``inline literall``
- ``inline literall``
- ``inline literall``
- This item has multiple paragraphs.

This item has multiple paragraphs.
- This item has multiple paragraphs.

This item has multiple paragraphs.


Second list level
^^^^^^^^^^^^^^^^^
Expand All @@ -151,13 +192,18 @@ Second list level

heh heh. child. try to beat this embed:

.. literalinclude:: test_py_module/test.py
:language: python
.. literalinclude:: api.rst
:language: rst
:linenos:
:lines: 1-10

- and another. `yahoo <http://www.yahoo.com>`_
- `yahoo <http://www.yahoo.com>`_
- ``hi``
- how about an admonition?

.. note::
This is a note nested in a list.

- and hehe

But deeper down the rabbit hole
Expand Down Expand Up @@ -192,11 +238,11 @@ Hlists
.. hlist::
:columns: 2

- .. figure:: static/yi_jing_01_chien.jpg
- .. figure:: https://source.unsplash.com/200x200/daily?cute+animals

This is a short caption for a figure.

- .. figure:: static/yi_jing_01_chien.jpg
- .. figure:: https://source.unsplash.com/200x200/daily?cute+animals

This is a long caption for a figure. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Donec porttitor dolor in odio posuere, vitae ornare libero mattis. In lobortis justo vestibulum nibh aliquet, non.
Expand Down Expand Up @@ -290,15 +336,11 @@ List Tables

.. list-table:: This is a list table with images in it.

* - .. figure:: static/yi_jing_01_chien.jpg
* - .. figure:: https://source.unsplash.com/200x200/daily?cute+animals

This is a short caption for a figure.

- .. figure:: static/yi_jing_01_chien.jpg
- .. figure:: https://source.unsplash.com/200x200/daily?cute+animals

This is a long caption for a figure. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Donec porttitor dolor in odio posuere, vitae ornare libero mattis. In lobortis justo vestibulum nibh aliquet, non.

.. meta::
:description lang=en:
Examples of table features in pydata-sphinx-theme.