Merge pull request #27 from treyhunner/update-docs

Document RelativesAdmin usage

.github/workflows/tests.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
 
     steps:
     - uses: actions/checkout@v1

.pre-commit-config.yaml

@@ -1,12 +1,22 @@
+exclude: '.git|.tox'
+default_stages: [commit]
+fail_fast: true
+
 repos:
--   repo: https://github.com/psf/black
-    rev: 22.3.0
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
     hooks:
-    - id: black
-      language_version: python3.7
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  # Ruff version.
-  rev: v0.0.275
-  hooks:
-    - id: ruff
-      args: [--fix, --exit-non-zero-on-fix]
+      - id: check-yaml
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.1.13
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.1.13
+    hooks:
+      - id: ruff-format

.readthedocs.yml

@@ -0,0 +1,20 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  builder: "dirhtml"
+  fail_on_warning: false
+
+formats:
+  - pdf
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CONTRIBUTING.rst

@@ -17,6 +17,25 @@ When creating a pull request, try to:
 .. _README: README.rst
 
 
+Linting & Pre-commit
+--------------------
+
+This project uses `ruff <https://docs.astral.sh/ruff/>`_ for both linting and auto-formatting code.
+
+This project also uses pre-commit to ensure linters and code formatters are run for all commits.
+Please install the ``pre-commit``:
+
+.. code-block:: bash
+
+    $ pip install pre-commit
+
+And then install the pre-commit hooks:
+
+.. code-block:: bash
+
+    $ pre-commit install
+
+
 Adding migrations
 -----------------
 
@@ -30,23 +49,37 @@ To make migrations you can run::
 Testing
 -------
 
-To install the package and its dependencies::
+To install the package and its dependencies:
+
+.. code-block:: bash
 
-    pip install -e .
+    $ pip install -e .
 
-Please add tests for your code and ensure existing tests don't break.  To run
-the tests against your code::
+Please add tests for your code and ensure existing tests don't break.
+To run the tests against your code:
 
-    python runtests.py
+.. code-block:: bash
+
+    $ python runtests.py
 
 Please use tox to test the code against supported Python and Django versions.
-First install tox::
+First install tox:
+
+.. code-block:: bash
+
+    $ pip install coverage tox
+
+To run tox:
+
+.. code-block:: bash
+
+    $ tox -p
 
-    pip install coverage tox
+To run tox and generate a coverage report (in ``htmlcov`` directory):
 
-To run tox and generate a coverage report (in ``htmlcov`` directory)::
+.. code-block:: bash
 
-    make test
+    $ make test
 
 
 Releases

Makefile

@@ -5,7 +5,7 @@ init:
 
 test:
 	coverage erase
-	tox
+	tox -p
 	coverage html
 
 fast_test:

README.rst

@@ -26,41 +26,41 @@ django-relatives
    :target: https://codecov.io/gh/treyhunner/django-relatives
    :alt: Codecov
 
-Utilities for linking to related objects in Django admin
-
-This app requires Django 3.2 or greater and Python 3.8 or greater.
+Utilities for linking to related objects in Django admin.
 
 
 Getting Help
 ------------
 
-Documentation for django-relatives is available at
-https://django-relatives.readthedocs.org/
-
-This app is available on `PyPI`_.
+See `the full documentation for django-relatives here <https://django-relatives.readthedocs.org/>`_.
 
-Submit issues on Github: https://github.com/treyhunner/django-relatives/issues
+This app is available on `PyPI <https://pypi.python.org/pypi/django-relatives/>`_.
 
-Pull requests are welcome.  Read the CONTRIBUTING file for tips on submitting
-a pull request.
+`Submit issues on Github <https://github.com/treyhunner/django-relatives/issues>`_.
 
-.. _PyPI: https://pypi.python.org/pypi/django-relatives/
+Pull requests are welcome.
+Read the ``CONTRIBUTING.rst`` file for tips on submitting a pull request.
 
 
 Screenshots
 -----------
 
-.. image:: https://raw.github.com/treyhunner/django-relatives/master/docs/images/contents_or_fk_link_example.png
+.. image:: https://raw.github.com/treyhunner/django-relatives/main/docs/images/object_edit_link_example.png
+   :alt: Use hyperlinks for foreign keys on change lists
+   :target: https://django-relatives.readthedocs.org/en/latest/usage.html#change-lists
+
+.. image:: https://raw.github.com/treyhunner/django-relatives/main/docs/images/contents_or_fk_link_example.png
    :alt: Use hyperlinks for read-only foreign keys on change forms
-   :target: https://django-relatives.readthedocs.org/en/latest/usage.html#linking-to-foreign-keys
+   :target: https://django-relatives.readthedocs.org/en/latest/usage.html#change-forms
 
-.. image:: https://raw.github.com/treyhunner/django-relatives/master/docs/images/object_edit_link_example.png
+.. image:: https://raw.github.com/treyhunner/django-relatives/main/docs/images/related_objects_example.png
+   :alt: Link to reverse relations from from change forms
+   :target: https://django-relatives.readthedocs.org/en/latest/usage.html#reverse-relations
+
+.. image:: https://raw.github.com/treyhunner/django-relatives/main/docs/images/object_edit_link_example.png
    :alt: Add edit links to admin inlines
-   :target: https://django-relatives.readthedocs.org/en/latest/usage.html#customizing-inline-edit-links
+   :target: https://django-relatives.readthedocs.org/en/latest/usage.html#links-in-inlines
 
-.. image:: https://raw.github.com/treyhunner/django-relatives/master/docs/images/related_objects_example.png
-   :alt: Link to reverse relations from from change forms
-   :target: https://django-relatives.readthedocs.org/en/latest/usage.html#linking-to-reverse-relations
 
 Related Projects
 ----------------

docs/api.rst

@@ -1,6 +1,12 @@
 API Reference
 =============
 
+RelativesAdmin
+--------------
+
+.. automodule:: relatives
+   :members:
+
 Utility Functions
 -----------------
 

docs/conf.py

@@ -16,12 +16,17 @@
 import sys
 
 import django
+from django.conf import settings
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(".."))
 
+settings.configure(
+    DEBUG=True,
+    INSTALLED_APPS=["django.contrib.contenttypes"],
+)
 django.setup()
 
 project_directory = os.path.join(os.path.basename(__file__), "..")
@@ -49,7 +54,7 @@
 
 # General information about the project.
 project = "django-relatives"
-copyright = "2013, Trey Hunner"
+copyright = "2013-2024, Trey Hunner"
 
 parent_dir = os.path.dirname(os.path.dirname(__file__))
 
@@ -109,7 +114,7 @@ def get_version():
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "default"
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -121,7 +126,7 @@ def get_version():
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-# html_title = None
+html_title = f"relatives documentation v{release}"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 # html_short_title = None

docs/index.rst

@@ -1,8 +1,18 @@
-django-relatives
+Django Relatives
 ================
 
-django-relatives provides various utilites that make it easy to link related
-objects in the Django admin site.
+When using Django's admin site, I often find myself wishing I could easily visit model relations from my change lists and change forms.
+The django-relatives package is meant to do exactly this.
+
+Uses
+----
+
+The main usages of this Django app are:
+
+- :ref:`Linking to foreign keys in change lists <change_lists>`
+- :ref:`Linking to foreign keys in change forms <change_forms>`
+- :ref:`Linking to reverse relations on change forms <reverse_relations>`
+- :ref:`Linking to foreign keys in inlines <links_in_inlines>`
 
 Contents
 --------
@@ -16,27 +26,12 @@ Contents
 Contributing
 ------------
 
-Visit the project `on Github`_ to view the source, submit issues and pull
-requests.
+Visit the project `on Github`_ to view the source, submit issues and pull requests.
 
 .. _on github: https://github.com/treyhunner/django-relatives
 
-Examples
---------
-
-Turn read-only foreign key fields into hyperlinks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. figure:: images/object_edit_link_example.png
-
-Link to child objects in the sidebar
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. figure:: images/related_objects_example.png
-
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`search`
-

docs/requirements.txt

@@ -0,0 +1,2 @@
+Sphinx==7.2.6
+furo==2023.9.10