Docs improvements.

CHANGELOG.rst

@@ -10,11 +10,7 @@ Changelog
 
 .. image:: https://img.shields.io/badge/GitHub-sponsor-ff69b4
   :target: https://github.com/sponsors/jab
-  :alt: Sponsor through GitHub
-
-.. image:: https://img.shields.io/github/sponsors/jab
-   :target: https://github.com/sponsors/jab
-   :alt: Sponsors on GitHub
+  :alt: Sponsor
 
 
 :sup:`If you or your organization depends on bidict,

CONTRIBUTING.rst

@@ -40,47 +40,23 @@ Getting Started
 Making Changes
 --------------
 
-.. note:: You can now use
-   `GitPod.io <https://gitpod.io/#https://github.com/jab/bidict>`__
-   to get an already-configured development environment inside your browser
-   in which you can make, test, and submit your changes to bidict.
-
-.. note:: You can also work on bidict in a Visual Studio Code
-   `devcontainer environment <https://code.visualstudio.com/docs/remote/containers>`__
-   which will install development dependencies and some helpful VS Code
-   extensions for you.
-
-   Try ``Remote-Containers: Clone Repository in Container Volume...`` on this
-   repository. You may need to reload your VS Code window after it finishes
-   cloning and installing extensions, which it should prompt you to do.
-
-   In a devcontainer, you don't need to worry about the below steps of making a
-   virtualenv or configuring EditorConfig or pre-commit, those will be part of
-   your development environment by default.
-
-- Before making changes, please
-  (create a `virtualenv <http://virtualenv.pypa.io>`__ and)
-  install the extra packages required for development
-  if you haven't already:
-  ``pip install -r requirements/test.txt -r requirements/lint.txt -r requirements/docs.txt``
-
-  We use `EditorConfig <https://editorconfig.org/>`__
-  and `pre-commit <https://pre-commit.com/>`__
-  to help achieve uniform style and quality standards
-  across a diversity of development environments.
-
-  pre-commit gets installed when you run the command above
-  and ensures that various code checks are run before every commit
-  (look in ``.pre-commit-config.yaml`` to see which hooks are run).
-  Ensure the configured hooks are installed by running
-  ``pre-commit install --install-hooks``.
-
-  EditorConfig allows us to provide a single ``.editorconfig`` file
-  to configure settings like indentation consistently
-  across a variety of supported editors.
-  See https://editorconfig.org/#download to install the plugin for your editor.
-
-- Create a topic branch off of main for your changes:
+- Recommended: You can work on bidict in a Visual Studio Code
+  `devcontainer environment <https://code.visualstudio.com/docs/remote/containers>`__,
+  where development dependencies and some helpful VS Code extensions
+  are installed inside the dev container environment for you.
+
+  Try ``Remote-Containers: Clone Repository in Container Volume...`` on this
+  repository. You may need to reload your VS Code window after it finishes
+  cloning and installing extensions, which it should prompt you to do.
+
+- If not using a VSCode devcontainer, you can try the following
+  to set up a development environment manually:
+  ``./init_dev_env``
+
+- Note that `pre-commit <https://pre-commit.com/>`__
+  is used to help achieve uniform style and quality standards.
+
+- Create a topic branch off of ``main`` for your changes:
   ``git checkout -b <topic> main``
 
 - Make commits of logical units.
@@ -134,6 +110,9 @@ Submitting Changes
 Sponsoring
 ----------
 
+.. Some of the following badges are duplicated on other pages.
+   Would use `.. include::` but GitHub's renderer doesn't support it.
+
 .. image:: https://img.shields.io/badge/GitHub-sponsor-ff69b4
   :target: https://github.com/sponsors/jab
   :alt: Sponsor through GitHub
@@ -146,13 +125,6 @@ Sponsoring
   :target: https://www.paypal.com/cgi-bin/webscr?cmd=_xclick&business=jabronson%40gmail%2ecom&lc=US&item_name=Sponsor%20bidict
   :alt: Sponsor through PayPal
 
-.. image:: https://img.shields.io/github/sponsors/jab
-   :target: https://github.com/sponsors/jab
-   :alt: Sponsors on GitHub
-
-.. duplicated in README.rst
-   (would use `.. include::` but GitHub doesn't understand it)
-
 Bidict is the product of thousands of hours of my unpaid work
 over the ~15 years that I've been the sole maintainer.
 

README.rst

@@ -21,8 +21,8 @@ Status
    :target: https://bidict.readthedocs.io/en/main/
    :alt: Documentation
 
-.. image:: https://github.com/jab/bidict/actions/workflows/test.yml/badge.svg
-   :target: https://github.com/jab/bidict/actions
+.. image:: https://github.com/jab/bidict/actions/workflows/test.yml/badge.svg?branch=main
+   :target: https://github.com/jab/bidict/actions/workflows/test.yml?query=branch%3Amain
    :alt: GitHub Actions CI status
 
 .. image:: https://img.shields.io/pypi/l/bidict.svg
@@ -33,13 +33,9 @@ Status
    :target: https://pepy.tech/project/bidict
    :alt: PyPI Downloads
 
-.. image:: https://img.shields.io/github/sponsors/jab
-   :target: https://github.com/sponsors/jab
-   :alt: Sponsors on GitHub
-
 .. image:: https://img.shields.io/badge/GitHub-sponsor-ff69b4
    :target: https://github.com/sponsors/jab
-   :alt: Sponsor on GitHub
+   :alt: Sponsor
 
 
 Features
@@ -60,7 +56,7 @@ Features
   concise, well-factored, fully type-hinted Python code
   that is optimized for running efficiently
   as well as for long-term maintenance and stability
-  (not to mention `joy <#learning-from-bidict>`__ :)
+  (as well as `joy <#learning-from-bidict>`__)
 
 - Extensively `documented <https://bidict.readthedocs.io>`__
 
@@ -147,7 +143,7 @@ Release Notifications
 ---------------------
 
 .. duplicated in CHANGELOG.rst:
-   (would use `.. include::` but GitHub doesn't understand it)
+   (Would use `.. include::` but GitHub's renderer doesn't support it.)
 
 Watch `bidict releases on GitHub <https://github.com/jab/bidict/releases>`__
 to be notified when new versions of bidict are published.
@@ -182,16 +178,12 @@ Sponsoring
 ----------
 
 .. duplicated in CONTRIBUTING.rst
-   (would use `.. include::` but GitHub doesn't understand it)
+   (Would use `.. include::` but GitHub's renderer doesn't support it.)
 
 .. image:: https://img.shields.io/badge/GitHub-sponsor-ff69b4
   :target: https://github.com/sponsors/jab
   :alt: Sponsor through GitHub
 
-.. image:: https://img.shields.io/github/sponsors/jab
-   :target: https://github.com/sponsors/jab
-   :alt: Sponsors on GitHub
-
 Bidict is the product of thousands of hours of my unpaid work
 over the ~15 years that I've been the sole maintainer.
 
@@ -246,6 +238,3 @@ try these alternate links instead:
 .. [#fn-learning] `<https://bidict.readthedocs.io/learning-from-bidict.html>`__ | `<docs/learning-from-bidict.rst>`__
 
 .. [#fn-contributing] `<https://bidict.readthedocs.io/contributors-guide.html>`__ | `<CONTRIBUTING.rst>`__
-
-
-.. image:: https://static.scarf.sh/a.png?x-pxid=05e3c4e4-eaa7-41a1-84c2-ec14413115f8

docs/_static/bidict-types-diagram.dot

@@ -5,37 +5,43 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 
-// See build-bidict-types-diagram.sh for how to generate a PNG from this file.
+// See build-bidict-types-diagram for how to generate a PNG from this file.
 
 digraph G {
-  rankdir=BT
   dpi=300
   node [fontsize="12", shape="box"]
 
+  subgraph bidicts {
+    node [fontname="Operator Mono SSm Lig Book"]
+
+    bidict [label="bidict.bidict"]
+    frozenbidict [label="bidict.frozenbidict"]
+    OrderedBidict [label="bidict.OrderedBidict"]
+
+    { rank=same bidict frozenbidict OrderedBidict }
+  }
+
   subgraph ABCs {
-    node [fillcolor="#EFEFEF", color="#666666", fontcolor="#333333", style="filled", fontname="Operator Mono SSm Lig Book"]
+    node [fillcolor="#EFEFEF", color="#666666", fontcolor="#333333", style="filled,rounded", fontname="Operator Mono SSm Lig Book Italic", fontsize="10"]
     Mapping [label="collections.abc.Mapping"]
     MutableMapping [label="collections.abc.MutableMapping"]
     Hashable [label="collections.abc.Hashable"]
+
     MutableMapping -> Mapping
+
     { rank=same Mapping MutableMapping Hashable }
 
-    BidirectionalMapping [label="bidict._abc.BidirectionalMapping", style="filled, bold", fontcolor="black", fontname="Operator Mono SSm Lig Book Italic"]
-    MutableBidirectionalMapping [label="bidict._abc.MutableBidirectionalMapping", style="filled, bold", fontcolor="black", fontname="Operator Mono SSm Lig Book Italic"] BidirectionalMapping -> Mapping
+    BidirectionalMapping [label="bidict.BidirectionalMapping"]
+    MutableBidirectionalMapping [label="bidict.MutableBidirectionalMapping"]
+
+    { rank=same BidirectionalMapping MutableBidirectionalMapping }
+
+    BidirectionalMapping -> Mapping
     MutableBidirectionalMapping -> BidirectionalMapping
     MutableBidirectionalMapping -> MutableMapping
   }
 
-  subgraph {
-    node [style="bold", fontname="Operator Mono SSm Lig Book"]
-
-    bidict [label="bidict.bidict"]
-    frozenbidict [label="bidict.frozenbidict"]
-    OrderedBidict [label="bidict.OrderedBidict"]
-
-    bidict -> { MutableBidirectionalMapping }
-    OrderedBidict -> { MutableBidirectionalMapping }
-    frozenbidict -> { BidirectionalMapping, Hashable }
-    { rank=same bidict frozenbidict OrderedBidict }
-  }
+  bidict -> { MutableBidirectionalMapping }
+  OrderedBidict -> { MutableBidirectionalMapping }
+  frozenbidict -> { BidirectionalMapping, Hashable }
 }

docs/_static/custom.js

@@ -16,5 +16,4 @@ document.addEventListener('DOMContentLoaded', function() {
 
   var sidebarUl = document.querySelector('.sidebar-tree > ul');
   sidebarUl.insertAdjacentHTML('beforeend', '<li class="toctree l1"><a class="reference external" href="https://github.com/jab/bidict">GitHub Repository</a></li>');
-  sidebarUl.insertAdjacentHTML('afterend', '<div><img src="https://static.scarf.sh/a.png?x-pxid=15b5b7c1-9453-4ab6-8a82-8cfa0f4db4f9" /></div>')
 });

docs/addendum.rst

@@ -4,18 +4,18 @@ Addendum
 Performance
 -----------
 
-:mod:`bidict` is written to be as performant as possible
+Bidict is written to be as performant as possible
 without sacrificing other important goals,
 such as safety, portability, and maintainability.
 
-In general, using a :mod:`bidict` to maintain a bidirectional mapping
+In general, using a bidict to maintain a bidirectional mapping
 should exhibit about the same performance as
 keeping two mutually-inverse one-directional mappings
 in sync manually.
 The test suite includes benchmarks so that bidict's performance
 can be continuously measured and improved.
 
-If you spot an opportunity to improve :mod:`bidict`'s performance further,
+If you spot an opportunity to improve bidict's performance further,
 please don't hesitate to
 :doc:`file an issue or submit a pull request <contributors-guide>`.
 
@@ -50,7 +50,7 @@ and that its memory will therefore be reclaimed immediately.
 
 .. note::
 
-   In PyPy this is not an issue, as PyPy doesn't use reference counts.
+   In PyPy this does not occur, as PyPy doesn't use reference counts.
    The memory for unreferenced objects in PyPy is only reclaimed
    when GC kicks in, which is unpredictable.
 

docs/basic-usage.rst

@@ -14,14 +14,18 @@ giving access to inverse items:
 
 .. doctest::
 
+   >>> element_by_symbol.inverse
+   bidict({'hydrogen': 'H'})
    >>> element_by_symbol.inverse['helium'] = 'He'
+   >>> element_by_symbol
+   bidict({'H': 'hydrogen', 'He': 'helium'})
    >>> del element_by_symbol.inverse['hydrogen']
    >>> element_by_symbol
    bidict({'He': 'helium'})
 
-:class:`bidict.bidict` supports the rest of the
-:class:`collections.abc.MutableMapping` interface
-as well:
+Both a :class:`bidict.bidict` and its inverse
+support the entire
+:class:`collections.abc.MutableMapping` interface:
 
 .. doctest::
 
@@ -41,9 +45,10 @@ as well:
    >>> element_by_symbol.inverse.pop('mercury')
    'Hg'
 
-Because inverse items are maintained alongside forward items,
-referencing a :class:`~bidict.bidict`'s inverse
-is always a constant-time operation.
+The inverse is automatically kept up-to-date.
+Referencing a :class:`~bidict.bidict`'s inverse
+is always a constant-time operation;
+the inverse is not computed on demand.
 
 
 Values Must Be Hashable
@@ -359,15 +364,14 @@ Interop
 +++++++
 
 :class:`~bidict.bidict`\s interoperate well with other types of mappings.
-For example, they support (efficient) polymorphic equality testing:
+For example, they support efficient polymorphic equality testing:
 
 .. doctest::
 
    >>> bidict(a=1) == dict(a=1)
    True
 
-And converting back and forth works as expected
-(assuming no :ref:`value duplication <basic-usage:Values Must Be Unique>`):
+And converting back and forth works as expected:
 
 .. doctest::
 
@@ -376,12 +380,15 @@ And converting back and forth works as expected
    >>> bidict(dict(a=1))
    bidict({'a': 1})
 
+(Just remember that if there were any
+:ref:`duplicate values <basic-usage:Values Must Be Unique>`
+in the dict passed to :class:`~bidict.bidict`,
+it would trigger a :class:`~bidict.ValueDuplicationError`.)
+
 See the :ref:`other-bidict-types:Polymorphism` section
 for more interoperability documentation.
 
 ----
 
-Hopefully :mod:`bidict` feels right at home
-among the Python built-ins you already know.
 Proceed to :doc:`other-bidict-types`
 for documentation on the remaining bidict variants.

docs/conftest.py

@@ -22,4 +22,5 @@ def _add_doctest_globals(doctest_namespace: t.MutableMapping[str, t.Any]) -> Non
     doctest_namespace['Mapping'] = Mapping
     doctest_namespace['MutableMapping'] = MutableMapping
     doctest_namespace['pypy'] = sys.implementation.name == 'pypy'
+    doctest_namespace['sys'] = sys
     doctest_namespace.update(i for i in vars(bidict).items() if not i[0].startswith('_'))