move away from rst (for md) where it makes sense

.gitignore

@@ -59,6 +59,7 @@ docs/auto_examples/
 docs/.jupyter_cache/
 docs/sg_execution_times.rst
 .ipynb_checkpoints
+great-docs/
 
 # PyBuilder
 target/

AUTHORS.md

@@ -0,0 +1,9 @@
+# Credits
+
+## Development Lead
+
+- Paul M. Hobson <pmhobson@gmail.com>
+
+## Contributors
+
+- Pierre Haessig

CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing
+
+Contributions are welcome, and they are greatly appreciated! Every
+little bit helps, and credit will always be given.
+
+You can contribute in many ways:
+
+## Types of Contributions
+
+### Report Bugs
+
+Report bugs at <https://github.com/matplotlib/mpl-probscale/issues>.
+
+If you are reporting a bug, please include:
+
+- Your operating system name and version.
+- Any details about your local setup that might be helpful in troubleshooting.
+- Detailed steps to reproduce the bug.
+
+### Fix Bugs
+
+Look through the GitHub issues for bugs. Anything tagged with "bug"
+and "help wanted" is open to whoever wants to implement it.
+
+### Implement Features
+
+Look through the GitHub issues for features. Anything tagged with "enhancement"
+and "help wanted" is open to whoever wants to implement it.
+
+### Write Documentation
+
+mpl-probscale could always use more documentation, whether as part of the
+official mpl-probscale docs, in docstrings, or even on the web in blog posts,
+articles, and such.
+
+### Submit Feedback
+
+The best way to send feedback is to file an issue at
+<https://github.com/matplotlib/mpl-probscale/issues>.
+
+If you are proposing a feature:
+
+- Explain in detail how it would work.
+- Keep the scope as narrow as possible, to make it easier to implement.
+- Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+## Get Started!
+
+Ready to contribute? Here's how to set up `probscale` for local development.
+
+1. Fork the `probscale` repo on GitHub.
+2. Clone your fork locally:
+
+   ```console
+   $ git clone git@github.com:your_name_here/probscale.git
+   ```
+
+3. Install your local copy into a virtual environment with
+   [uv](https://docs.astral.sh/uv/):
+
+   ```console
+   $ cd probscale/
+   $ uv sync
+   ```
+
+4. Create a branch for local development:
+
+   ```console
+   $ git checkout -b name-of-your-bugfix-or-feature
+   ```
+
+   Now you can make your changes locally.
+
+5. When you're done making changes, check that your changes pass the tests:
+
+   ```console
+   $ uv run pytest --mpl
+   ```
+
+6. Commit your changes and push your branch to GitHub:
+
+   ```console
+   $ git add <files you want to stage>
+   $ git commit -m "Your detailed description of your changes."
+   $ git push origin name-of-your-bugfix-or-feature
+   ```
+
+7. Submit a pull request through the GitHub website.
+
+Matplotlib has good info on working with [source code] using [git and GitHub].
+
+[source code]: https://matplotlib.org/devdocs/devel/coding_guide.html
+[git and GitHub]: https://matplotlib.org/devdocs/devel/development_workflow.html
+
+## Pull Request Guidelines
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put
+   your new functionality into a function with a docstring, and add the
+   feature to the list in the README.
+3. The pull request should work for Python 3.11 and higher. Check the
+   GitHub Actions results and make sure that the tests pass for all
+   supported Python versions.
+
+## Tips
+
+To run a subset of tests:
+
+```console
+$ uv run pytest probscale/tests/test_probscale.py
+```

README.md

@@ -37,6 +37,8 @@ pip install -e .
 Simply importing `probscale` lets you use probability scales in your matplotlib figures:
 
 ```python
+from pathlib import Path
+
 from matplotlib import pyplot
 from scipy import stats
 import probscale  # nothing else needed
@@ -64,7 +66,10 @@ fig, axes = pyplot.subplots(nrows=N, figsize=(9, N - 1), constrained_layout=True
 for scale, ax in zip(scales, axes.flat):
     ax.set_xscale(**scale["scale"])
     ax.text(0.0, 0.1, scale["label"] + " →", transform=ax.transAxes)
-    ax.set_xlim(left=0.5, right=99.5)
+
+    factor = 100 if scale["scale"]["value"] == "logit" else 1
+    ax.set_xlim(left=0.5 / factor, right=99.5 / factor)
+
     ax.set_yticks([])
     ax.spines.left.set_visible(False)
     ax.spines.right.set_visible(False)

docs/api.md

@@ -0,0 +1,11 @@
+# API Reference
+
+```{toctree}
+:maxdepth: 2
+
+api/viz.rst
+api/probscale.rst
+api/formatters.rst
+api/transforms.rst
+api/validate.rst
+```

docs/authors.md

@@ -0,0 +1,2 @@
+```{include} ../AUTHORS.md
+```

docs/conf.py

@@ -83,6 +83,9 @@
 
 # -- myst-nb (tutorial notebooks) --------------------------------------------
 
+myst_enable_extensions = ["colon_fence", "deflist", "dollarmath"]
+myst_heading_anchors = 3
+
 nb_execution_mode = "auto"
 nb_execution_timeout = 600
 nb_execution_raise_on_error = True

docs/contributing.md

@@ -0,0 +1,2 @@
+```{include} ../CONTRIBUTING.md
+```

docs/examples/example.py

@@ -37,7 +37,10 @@
 for scale, ax in zip(scales, axes.flat):
     ax.set_xscale(**scale["scale"])
     ax.text(0.0, 0.1, scale["label"] + " →", transform=ax.transAxes)
-    ax.set_xlim(left=0.5, right=99.5)
+
+    factor = 100 if scale["scale"]["value"] == "logit" else 1
+    ax.set_xlim(left=0.5 / factor, right=99.5 / factor)
+
     ax.set_yticks([])
     ax.spines.left.set_visible(False)
     ax.spines.right.set_visible(False)

docs/index.md

@@ -0,0 +1,34 @@
+```{include} ../README.md
+:relative-docs: .
+:relative-images:
+```
+
+## Documentation
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+installation
+tutorial/getting_started.ipynb
+tutorial/closer_look_at_viz.ipynb
+tutorial/closer_look_at_plot_pos.ipynb
+auto_examples/index
+altair/index
+api
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+:caption: Project
+
+authors
+contributing
+```
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`