Documentation updates

.gitignore

@@ -1,5 +1,6 @@
 .idea/
 models.png
+cliff.toml
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

CHANGELOG.md → CHANGELOG.rst

@@ -1,13 +1,35 @@
-# Change Log
+Change Log
+==========
 
-## 0.4
+1.0 
+---
+
+- Merge design changes into ``main`` branch.
+- Update README with new instructions.
+
+0.8
+---
+
+- Implementation of django_tables2 for displaying postal objects.
+- First draft of a working map interface. 
+- Derive postal routes by calculating the path a postal object travels (sender, postmark, censor, recipient).
+
+0.7
+---
+
+- Implementation of data importing script.
+- Implementation of image importing script.
+
+0.4
+---
 
 - Added starter templates for the homepage, about page, and object display.
 - Updated model to account for related images.
 - Updated model to account for a collection an individual object belongs to.
 - Migrated AuthUser to AllAuth.
 
-## 0.3
+0.3
+---
 
 - Initial scaffolding and data model setup. This is a work in progress and is not yet ready for use.
 - The project runs a custom AuthUserModel for getting started,

DEVNOTES.rst

@@ -63,7 +63,7 @@ Initial setup and installation:
 Install pre-commmit hooks
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The project uses `pre-commit <https://pre-commit.com/>`_ to install and manage commit hooks to ensure consistently formatted code. To install, run::
+The project uses `pre-commit <https://pre-commit.com/>`_ to install and manage commit hooks to ensure consistently formatted code. To install, run:
 
 .. code-block:: bash
 
@@ -98,7 +98,6 @@ Server Installation
 
 .. code-block:: bash
 
-    python manage.py loaddata postcards/fixtures/locations.yaml
     python manage.py loaddata postcards/fixtures/languages.yaml
 
 - Next, we need to load the postal data. The postal data is stored in an Excel file (see the Project Manager for access). To load the data, run the following command (there are default values in the `Makefile` if you run `make loadobjects`):
@@ -109,62 +108,34 @@ Server Installation
 
 - Once these steps are complete, the current set of working data should be available.
 
-Models 
-======
+Data Models 
+===========
 
-Object Model
-------------
-
-The ``Object`` model represents a postcard object and is defined as follows:
-
-- ``title``: CharField, the title of the postcard.
-- ``description``: TextField, a detailed description of the postcard.
-- ``date_received``: DateField, the date the postcard was received.
-- ``date_sent``: DateField, the date the postcard was sent.
-- ``date_of_correspondence``: DateField, the date of correspondence.
-- ``notes``: TextField, additional notes about the postcard.
-- ``collection``: ManyToManyField to `Collection`, representing the collection(s) to which the postcard belongs.
-- ``postmark``: ManyToManyField to `Postmark`, representing postmark information associated with the postcard.
-
-Collection Model
------------------
-
-The ``Collection`` model represents a collection to which postcards belong and is defined as follows:
-
-- ``name``: CharField, the name of the collection.
-
-Location Model
------------------
-
-The ``Location`` model represents a town or city associated with postmark information and is defined as follows:
+Detailed `model and database documentation <https://dbdocs.io/hepplerj/Arnhem-Postal>`_ is autogenerated and hosted via dbdocs.io.
 
-- ``town_city``: CharField, the name of the town or city.
-
-Postmark Model
-----------------
-
-The ``Postmark`` model represents postmark information and is defined as follows:
+Data Importing
+==============
 
-- ``location``: ForeignKey to ``Location``, representing the town or city where the postmark was made.
-- ``date``: DateField, the date of the postmark.
-- ``ordered_by_arrival``: IntegerField, indicating the order of arrival (e.g., 1 for postmark 1, 2 for postmark 2).
+There are several import scripts available for getting data into the system. They will not likely be used since the RRCHNM team will be providing a PostgreSQL dump of the data, but are available if data importing is happening from scratch.
 
-Import Script
-==============
+load_objects
+------------
 
-The import script (``load_objects.py``) is designed to load postcard data from an Excel file into the database. It performs the following actions:
+The import scripts are designed to load data from an Excel file into the database. It performs the following actions:
 
 1. Reads data from the Excel file using ``pandas``.
-2. Iterates through each row of the data, creating or updating ``Object`` instances.
+2. Iterates through each row of the data, creating or updating model instances.
 3. Handles various data validations for date fields, notes, and postmark information.
 4. Associates postcards with people, collections, and postmark information.
-5. Before running this script, you must load the ``Locations`` and ``Languages`` fixtures.
 
 Usage
 ------
 
-To use the script, run the following command:
-
-.. code-block:: bash
+The management scripts are located in the ``postcards/management/commands`` directory. To load all data from scratch, they must be run in the following order: 
 
-    python manage.py load_objects path/to/excel/file.xlsx
+1. ``poetry run python manage.py loaddata languages.yaml``: Load the languages fixture.
+2. ``poetry run python manage.py load_locations --filepath="./arnhemv.xlsx" --sheet="Database ready``: Load the locations from the spreadsheet.
+3. ``poetry run python manage.py load_transcriptions --filepath="./arnhemv.xlsx" --sheet="Database ready"``: Load the transcriptions from the spreadsheet.
+4. ``poetry run python manage.py load_tags --filepath="./arnhemv.xlsx" --sheet="Database ready"``: Load the tags from the spreadsheet.
+5. ``poetry run python manage.py load_objects --filepath="./arnhemv.xlsx" --sheet="Database ready"``: Load the objects from the spreadsheet.
+6. ``poetry run python manage.py populate_images``: Load images that are stored in the ``static/upload`` directory.

Makefile

@@ -39,6 +39,9 @@ dumpdata :
 graph_illustrate :
 	poetry run python3 manage.py graph_models -a -g -o models.png
 
+docs : 
+	poetry run sphinx-build -b html docs/source/ docs/build/
+
 # Docker helpers
 docker-up : 
 	docker-compose up -d

config/settings.py

@@ -102,6 +102,7 @@
     "postcards",
     "pages",
     "maps",
+    "docs",
 ]
 
 INSTALLED_APPS = DJANGO_APPS + THIRD_PARTY_APPS + LOCAL_APPS

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/architecture.rst

@@ -0,0 +1,13 @@
+Architecture
+============
+
+.. toctree::
+   :maxdepth: 2
+
+
+Overview
+--------
+
+The Arnhem Postal History Project Django application has a single application: The :mod:`arnhem-app.postcards` application handles all related models, functionality, and views for viewing and interacting with postal material, people, and historical documents, while :class:`~arnhem-app.maps` handles the interface for the interactive map. 
+
+More detailed `database documentation <https://dbdocs.io/hepplerj/Arnhem-Postal>`_ is autogenerated and hosted via dbdocs.io.

docs/source/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst

docs/source/conf.py

@@ -0,0 +1,81 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#path-setup
+import os
+import sys
+
+# import django
+
+sys.path.insert(0, os.path.abspath("."))
+os.environ["DJANGO_SETTINGS_MODULE"] = "config.settings"
+# django.setup()
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Arnhem Postal History"
+copyright = "2024, Roy Rosenzweig Center for History and New Media"
+author = "The Roy Rosenzweig Center for History and New Media"
+description = "Django web application for the Arnhem Postal History Project"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]
+
+html_theme_options = {
+    "description": description,
+    "github_user": "chnm",
+    "github_repo": "arnhem-postal",
+    "codecov_button": True,
+}
+
+# html_sidebars = {
+#     "**": [
+#         "about.html",
+#         "navigation.html",
+#         "localtoc.html",
+#         "searchbox.html",
+#         "sidebar_footer.html",
+#     ],
+# }
+
+# Configure for intersphinx for Python standard library, Django,
+# and local dependencies with sphinx docs.
+intersphinx_mapping = {
+    "https://docs.python.org/3/": None,
+    "django": ("https://django.readthedocs.org/en/latest/", None),
+    "viapy": ("https://viapy.readthedocs.io/en/latest/", None),
+}
+
+
+coverage_ignore_pyobjects = [
+    # django auto-generated model methods
+    "clean_fields",
+    "get_deferred_fields",
+    "get_(next|previous)_by_(created|last_modified|modified)",
+    "refresh_from_db",
+    "get_.*_display",  # django auto-generated method for choice fields
+    "get_doc_relation_list",  # multiselectfield auto method
+]
+
+# coverage_statistics_to_report = coverage_statistics_to_stdout = False

docs/source/devnotes.rst

@@ -0,0 +1 @@
+.. include:: ../../DEVNOTES.rst

docs/source/index.rst

@@ -0,0 +1,21 @@
+.. Arnhem Postal History documentation master file, created by
+   sphinx-quickstart on Tue Apr 16 11:09:32 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Arnhem Postal History's documentation!
+=================================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   architecture
+   devnotes
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`