Merge pull request #19 from lsst-sqre/tickets/DM-40967

DM-40967: Improve default CSS styles

changelog.d/20231004_112117_jsick_DM_40967.md

@@ -0,0 +1,13 @@
+### New features
+
+- Improved styling:
+
+  - Style the permalink icon
+  - Style code blocks
+  - Style admonitions
+  - Style the metadata in the sidebars
+  - Style footnotes
+  - Style citations
+  - Style quotes
+  - Style tables and add a `wraptables`` Sphinx extension (included with the technote extension set) that wraps table elements in a `figure` to ensure wide tables have horizontal scrollbars
+  - Improve layout in the mobile view

demo/index.rst

@@ -12,10 +12,38 @@ Demo technote
 Introduction
 ============
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. [#]_ Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
 
+Lorem ipsum [Ref]_ dolor sit amet.
+
+.. [Ref] Book or article reference, URL or whatever.
+
+Here is a quote:
+
+   This is a quote.
+
+   It can span multiple paragraphs.
+
+Quotes with attribution:
+
+   This is a quote.
+
+   It can span multiple paragraphs.
+
+   -- The Developer
+
+An epigraph:
+
+.. epigraph::
+
+   This is an epigraph.
+
+   -- The Developer
+
+.. [#] Footnote text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
 Method
 ======
 
@@ -34,6 +62,258 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetr
 
    print("Hello world")
 
+Code cells
+==========
+
+This is a long code cell:
+
+.. code-block:: Makefile
+   :caption: Makefile
+
+   .PHONY: update-deps
+   update-deps:
+   	pip install --upgrade pip-tools pip setuptools
+   	pip-compile --upgrade --build-isolation --generate-hashes --output-file server/requirements/main.hashed.txt server/requirements/main.in
+   	pip-compile --upgrade --build-isolation --generate-hashes --output-file server/requirements/dev.hashed.txt server/requirements/dev.in
+   	pip-compile --upgrade --build-isolation --allow-unsafe --output-file server/requirements/main.txt server/requirements/main.in
+   	pip-compile --upgrade --build-isolation --allow-unsafe --output-file server/requirements/dev.txt server/requirements/dev.in
+
+   .PHONY: init
+   init:
+   	pip install --editable "./client[dev]"
+   	pip install --editable ./server
+   	pip install --upgrade -r server/requirements/main.txt -r server/requirements/dev.txt
+   	rm -rf ./server.tox
+   	pip install --upgrade pre-commit tox
+   	pre-commit install
+
+   .PHONY: update
+   update: update-deps init
+
+   .PHONY: run
+   run:
+   	cd server && tox run -e=run
+
+Admonitions
+===========
+
+Some content.
+
+.. attention::
+
+   This is an attention notice.
+
+More content.
+
+.. caution::
+
+   This is a caution:
+
+   - First item
+   - Second item
+   - Third item
+
+.. danger::
+
+   This is a danger notice.
+
+.. error::
+
+   This is an error.
+
+.. hint::
+
+   This is a hint.
+
+.. important::
+
+   This is important.
+
+.. note::
+
+   This is a note.
+
+.. tip::
+
+   This is a tip.
+
+.. warning::
+
+   This is a warning.
+
+Lists
+=====
+
+A compact list (default):
+
+- First item
+- Second item
+
+  - First child item
+  - Second child item
+
+- Third item
+
+An unordered list with long content using the ``block-list`` class:
+
+.. rst-class:: block-list
+
+- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla.
+
+- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla.
+
+  - First child item
+
+  - Second child item
+
+- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla.
+
+A compact ordered list:
+
+#. First item
+#. Second item
+
+   #. First child item
+   #. Second child item
+
+#. Third item
+
+An ordered list with long content using the ``block-list`` class:
+
+.. rst-class:: block-list
+
+#. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla.
+
+#. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla.
+
+   #. First child item
+
+   #. Second child item
+
+#. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla.
+
+A definition list:
+
+term
+   This is a definition.
+
+term
+   This is a definition.
+
+   It can span multiple paragraphs.
+
+Figures
+=======
+
+.. figure:: https://placehold.co/600x400/000000/FFFFFF.png
+   :alt: A placeholder image
+
+   This is an image.
+
+Tables
+======
+
+.. These examples are from https://sphinx-themes.org/
+
+Grid Tables
+-----------
+
+Here's a grid table followed by a simple table:
+
++------------------------+------------+----------+----------+
+| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+| (header rows optional) |            |          |          |
++========================+============+==========+==========+
+| body row 1, column 1   | column 2   | column 3 | column 4 |
++------------------------+------------+----------+----------+
+| body row 2             | Cells may span columns.          |
++------------------------+------------+---------------------+
+| body row 3             | Cells may  | - Table cells       |
++------------------------+ span rows. | - contain           |
+| body row 4             |            | - body elements.    |
++------------------------+------------+----------+----------+
+| body row 5             | Cells may also be     |          |
+|                        | empty: ``-->``        |          |
++------------------------+-----------------------+----------+
+
+=====  =====  ======
+   Inputs     Output
+------------  ------
+  A      B    A or B
+=====  =====  ======
+False  False  False
+True   False  True
+False  True   True
+True   True   True
+=====  =====  ======
+
+Giant Tables
+^^^^^^^^^^^^
+
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+| Header 1   | Header 2   | Header 3  | Header 1   | Header 2   | Header 3  | Header 1   | Header 2   | Header 3  | Header 1   | Header 2   | Header 3  |
++============+============+===========+============+============+===========+============+============+===========+============+============+===========+
+| body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  |
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+| body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  |
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+| body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  |
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+| body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  |
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+
+Table containing code
+---------------------
+
+==================================== ===========================================
+Version                              Installing
+==================================== ===========================================
+Pradyun's pip fork and installer     .. code-block:: bash
+
+                                        pip install "pip @ git+https://github.com/pradyunsg/pip#20.3.3" "installer @ git+https://github.com/pradyunsg/installer"
+
+PyPI                                 .. code-block:: bash
+
+                                        pip install pip installer
+
+==================================== ===========================================
+
+List Tables
+-----------
+
+.. list-table:: List tables can have captions like this one.
+    :widths: 10 5 10 50
+    :header-rows: 1
+    :stub-columns: 1
+
+    * - List table
+      - Header 1
+      - Header 2
+      - Header 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu.
+    * - Stub Row 1
+      - Row 1
+      - Column 2
+      - Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu.
+    * - Stub Row 2
+      - Row 2
+      - Column 2
+      - Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu.
+    * - Stub Row 3
+      - Row 3
+      - Column 2
+      - Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu.
+
+.. list-table:: This is a list table with images in it.
+
+    * - .. figure:: https://source.unsplash.com/200x200/daily?cute+puppy
+
+           This is a short caption for a figure.
+
+      - .. figure:: https://source.unsplash.com/200x200/daily?cute+puppy
+
+           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.
+
 Results
 =======
 

src/assets/styles/base/_index.scss

@@ -1,2 +1,3 @@
 @use 'layout';
 @use 'typography';
+@use 'sphinx';

src/assets/styles/base/_layout.scss

@@ -43,15 +43,15 @@
 }
 
 /* Highlight key containers for debugging. */
-/* .sb-article {
-  border: 1px solid red;
-}
-.sb-sidebar-secondary {
-  border: 1px solid blue;
-}
-.sb-sidebar-primary {
-  border: 1px solid green;
-} */
+// .sb-article {
+//   border: 1px solid red;
+// }
+// .sb-sidebar-secondary {
+//   border: 1px solid blue;
+// }
+// .sb-sidebar-primary {
+//   border: 1px solid green;
+// }
 
 /*
  * Content container width.
@@ -65,6 +65,19 @@
   /* reset skeleton.css. Using 100vw means we get horizontal scrollbars. */
   width: auto;
 }
+
+@media (max-width: 42rem) {
+  .sb-article-container,
+  .sb-footer-content__inner {
+    width: 100vw;
+  }
+
+  body {
+    // experiment with using hyphens on phones
+    hyphens: auto;
+  }
+}
+
 @media (min-width: 42rem) {
   .sb-footer-content__inner,
   .drop-secondary-sidebar-for-full-width-content .sb-article,
@@ -75,9 +88,9 @@
   .match-content-width {
     width: 38rem;
   }
-  /* h1::after {
-    content: ' 42';
-  } */
+  // h1::after {
+  //   content: ' 42';
+  // }
 }
 @media (min-width: 46rem) {
   .sb-footer-content__inner,
@@ -89,9 +102,9 @@
   .match-content-width {
     width: 40rem;
   }
-  /* h1::after {
-    content: ' 46';
-  } */
+  // h1::after {
+  //   content: ' 46';
+  // }
 }
 @media (min-width: 50rem) {
   .sb-footer-content__inner,