fix: formatting of callouts

_config.yml

@@ -15,8 +15,6 @@ plugins:
 
 # Theme settings
 
-color_scheme: skhep
-
 logo: "/assets/images/logo.svg"
 
 # Enable or disable the site search
@@ -34,14 +32,15 @@ gh_edit_branch: "main"
 gh_edit_source: "docs"
 gh_edit_view_mode: "tree" # "tree" or "edit"
 
-# Exclude from processing.
-# The following items will not be processed, by default. Create a custom list
-# to override the default setting.
-# exclude:
-# - Gemfile
-# - Gemfile.lock
-# - node_modules
-# - vendor/bundle/
-# - vendor/cache/
-# - vendor/gems/
-# - vendor/ruby/
+callouts:
+ warning:
+ color: red
+ title: Warning
+ note:
+ color: yellow
+ title: Note
+ important:
+ color: green
+ title: Important
+ highlight:
+ color: blue

docs/pages/guides/coverage.md

@@ -25,7 +25,9 @@ Tools and libraries used to calculate, read, and visualize coverage reports:
 - `GitHub Actions`: allows users to automatically upload coverage reports to
  `Codecov`
 
-> ### Are there any alternatives?
+{: .note-title }
+
+> Are there any alternatives?
 >
 > `coverage.py` is a popular Python library used to calculate coverage values,
 > but it is usually paired with python's `unittest`. On the other hand,
@@ -34,7 +36,9 @@ Tools and libraries used to calculate, read, and visualize coverage reports:
 > recommend using Codecov because of its ease of use and integration with GitHub
 > Actions.
 
-> ### Should increasing the coverage value be my top priority?
+{: .highlight-title }
+
+> Should increasing the coverage value be my top priority?
 >
 > A low coverage percentage will definitely motivate you to add more tests, but
 > adding weak tests just for coverage's sake is not a good idea. The tests

docs/pages/guides/docs.md

@@ -243,11 +243,14 @@ def docs(session: nox.Session) -> None:
  parser.add_argument("--serve", action="store_true", help="Serve after building")
  args, posargs = parser.parse_known_args(session.posargs)
 
- session.install(".[docs]")
+ session.install("-e.[docs]")
  session.chdir("docs")
 
  session.run(
  "sphinx-build",
+ "-n", # nitpicky mode
+ "--keep-going", # show all errors
+ "-T", # full tracebacks
  "-b",
  "html",
  ".",

docs/pages/guides/gha_pure.md

@@ -17,10 +17,12 @@ procedure to make a "built" wheel is simple. At the end of this page, there is a
 recipe that can often be used exactly for pure Python wheels (if the previous
 recommendations were followed).
 
-> Note: Why make a wheel when there is nothing to compile? There are a multitude
-> of reasons that a wheel is better than only providing an sdist:
+{: .note }
+
+> Why make a wheel when there is nothing to compile? There are a multitude of
+> reasons that a wheel is better than only providing an sdist:
 >
-> - Wheels do not run setup.py, but simply install files into locations
+> - Wheels do not run `setup.py`, but simply install files into locations
 > - Lower install requirements - users don't need your setup tools
 > - Faster installs
 > - Safer installs - no arbitrary code execution

docs/pages/guides/packaging_classic.md

@@ -24,8 +24,8 @@ systems.
 Also see the [Python packaging guide][], especially the [Python packaging
 tutorial][].
 
-> <h2 class="no_toc">Note:</h2>
->
+{: .note }
+
 > Raw source lives in git and has a `setup.py`. You _can_ install directly from
 > git via pip, but normally users install from distributions hosted on PyPI.
 > There are three options: **A)** A source package, called an SDist and has a
@@ -39,8 +39,9 @@ tutorial][].
 > Python version and OS as well.
 >
 > Developer requirements (users of A or git) are generally higher than the
-> requirements to use B or C. Poetry creates SDists that include a setup.py, and
-> both alternate packing systems produce "normal" wheels.
+> requirements to use B or C. Poetry and optionally flit create SDists that
+> include a `setup.py`, and all alternate packing systems produce "normal"
+> wheels.
 
 ## Package structure (medium priority)
 
@@ -197,7 +198,9 @@ env:
 If you fill in the override version setting when triggering a manual workflow
 run, that version will be forced, otherwise, it works as normal.
 
-> Note: Make sure you have a good gitignore, probably starting from
+{: .note }
+
+> Make sure you have a good gitignore, probably starting from
 > [GitHub's Python one](https://github.com/github/gitignore/blob/main/Python.gitignore)
 > or using a [generator site](https://www.toptal.com/developers/gitignore).
 
@@ -434,6 +437,22 @@ global-exclude __pycache__ *.py[cod] .*
 
 Note that Scikit-build currently may have issues with MANIFEST.in.
 
+## Command line
+
+If you want to ship an "app" that a user can run from the command line, you need
+to add a `console_scripts` entry point. The form is:
+
+```ini
+[options.entry_points]
+console_scripts =
+ cliapp = packakge.__main__:main
+```
+
+The format is command line app name as the key, and the value is the path to the
+function, followed by a colon, then the function to call. If you use
+`__main__.py` as the file, then `python -m` + the module will also work to call
+the app.
+
 [^1]:
  You shouldn't ever have to run commands like this, they are implementation
  details of setuptools. For this command, you should use `python -m build -s`

docs/pages/guides/packaging_simple.md

@@ -23,15 +23,19 @@ eventually gain support in 2.0.
 Binaries mostly are unsupported in existing PEP 621 tools, though better support
 is coming.
 
-> ## Classic files
+{: .note-title }
+
+> Classic files
 >
 > These systems do not use or require `setup.py`, `setup.cfg`, or `MANIFEST.in`.
 > Those are for setuptools. Unless you are using setuptools, of course, which
 > still uses `MANIFEST.in`. You can convert the old files using
 > `pipx run hatch new --init` or with
 > [ini2toml](https://ini2toml.readthedocs.io/en/latest/).
 
-> ## Selecting a backend
+{: .highlight-title }
+
+> Selecting a backend
 >
 > Backends handle metadata the same way, so the choice comes down to how you
 > specify what files go into an SDist and extra features, like getting a version
@@ -219,20 +223,18 @@ This is tool specific.
 - [PDM info here](https://pdm.fming.dev/pyproject/tool-pdm/#include-and-exclude-package-files).
 - Setuptools still uses `MANIFEST.in`.
 
-<details markdown="1"><summary>Warning for Flit</summary>
-
-Flit will not use VCS (like git) to populate the SDist if you use standard
-tooling, even if it can do that using its own tooling. So make sure you list
-explicit include/exclude rules, and test the contents:
+{: .warning }
 
-```bash
-# Show SDist contents
-tar -tvf dist/*.tar.gz
-# Show wheel contents
-unzip -l dist/*.whl
-```
-
-</details>
+> Flit will not use VCS (like git) to populate the SDist if you use standard
+> tooling, even if it can do that using its own tooling. So make sure you list
+> explicit include/exclude rules, and test the contents:
+>
+> ```bash
+> # Show SDist contents
+> tar -tvf dist/*.tar.gz
+> # Show wheel contents
+> unzip -l dist/*.whl
+> ```
 
 ## Extras
 
@@ -260,6 +262,19 @@ recommend providing at least `test` and `docs`.
 
 ## Command line
 
+If you want to ship an "app" that a user can run from the command line, you need
+to add a `script` entry point. The form is:
+
+```toml
+[project.scripts]
+cliapp = "packakge.__main__:main"
+```
+
+The format is command line app name as the key, and the value is the path to the
+function, followed by a colon, then the function to call. If you use
+`__main__.py` as the file, then `python -m` + the module will also work to call
+the app.
+
 [flit]: https://flit.readthedocs.io
 [poetry]: https://python-poetry.org
 [pdm]: https://pdm.fming.dev

docs/pages/guides/pytest.md

@@ -29,7 +29,9 @@ in using pytest. The goals of writing good tests are:
 - Reporting: when things break, you should get good information about what
  broke.
 
-> ### What about other choices?
+{: .note-title }
+
+> What about other choices?
 >
 > The alternative library, `nose`, has been abandoned in favor of `pytest`,
 > which can run nose-style tests. The standard library has a test suite as well,

docs/pages/guides/tasks.md

@@ -214,6 +214,9 @@ def docs(session: nox.Session) -> None:
 
  session.run(
  "sphinx-build",
+ "-n", # nitpicky mode
+ "--keep-going", # show all errors
+ "-T", # full tracebacks
  "-b",
  "html",
  ".",

docs/pages/principles/design.md

@@ -44,6 +44,8 @@ follow the same principles as other code, like modularity, and be well tested.
 If you can get away with writing functions processing existing datatypes like a
 DataFrame, do so.
 
+{: .highlight }
+
 > It is better to have 100 functions operate on one data structure than 10
 > functions on 10 data structures.
 >

docs/pages/tutorials/dev-environment.md

@@ -78,13 +78,17 @@ of text to your prompt so you don't forget that you are in an environment.
 The activation script installs a function `deactivate`; type that at any time to
 leave the environment (or just close your shell).
 
-> <h4 class="no_toc">Optional Alternative</h4>
+{: .note-title }
+
+> Optional Alternative
 >
 > Alternatively, you can use the `virtualenv` package, which has the same syntax
 > as `venv` and is a little faster. Unlike `venv`, it is not built in to Python;
 > it has to be installed as `pip install virtualenv`.
 
-> <h4 class="no_toc">For Advanced Users Using Custom Shells</h4>
+{: .highlight-title }
+
+> For Advanced Users Using Custom Shells
 >
 > If you like a different shell, like fish, there are several `activate`
 > scripts; the default one expects a bash-like shell.

docs/pages/tutorials/module.md

@@ -74,7 +74,7 @@ automatically generate nice-looking HTML documentation later. Notable features:
 
 - There is a section listing input parameters, with the structure
 
- ```none
+ ```
  parameter_name : parameter_type
  optional description
  ```