chore: initial commit

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     = .
+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/conf.py

@@ -0,0 +1,41 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'A Module'
+copyright = 'Author Copyright'
+author = 'Author'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx_rtd_theme', 'sphinx.ext.todo', 'sphinxcontrib.mermaid', 'sphinxcontrib.youtube', 'sphinx_design']
+
+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 = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+
+# -- Esure TODOs are output (these should all be cleared before a commit)
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#directive-todo
+
+todo_include_todos = True
+todo_emit_warnings = True
+
+rst_prolog = """
+.. |LSP| replace:: :abbr:`LSP (Language Server Protocol)`
+.. |HMR| replace:: :abbr:`HMR (Hot Module Reload)`
+.. |IMHO| replace:: :abbr:`IMHO (In My Humble Opinion)`
+"""

docs/developers/alternatives.rst

@@ -0,0 +1,44 @@
+Alternatives
+============
+
+
+Can I use ``npm`` instead of ``pnpm``?
+--------------------------------------
+
+Replacing ``pnpm`` with ``npm`` is simple enough. You will need to modify the following:
+
+``package.json``
+  Change the ``packageManager`` entry, remove the ``scrips.preinstall`` entry. Check for any embedded ``pnpm`` commands and replace with the corresponding ``npm`` command. Most day-to-day 'heavy lifting' is done with :ref:`zx scripts` and these are independent of the package manager in use.
+``.github/workflows``
+  Check these as they use ``pnpm`` and a github cache action for ``pnpm``.
+
+.. _replacing github:
+Can I use an alternative to ``github``?
+---------------------------------------
+
+You can use another host for your version control and deployment but you will need to review and update:
+
+``.github/workflows``
+  These (obviously) rely on github being used\ [#F1]_. These build, package and deploy your module and its associated documentation.
+``module.json``
+  The elements in this file that change with each release are automatically maintained by the ``.github/workflows``. You will need to implement alternatives if you choose another host.
+
+
+.. _replacing sphinx:
+Can I replace the documentation system?
+---------------------------------------
+
+This template uses Docker to isolate a documentation system based on `Sphinx <https://www.sphinx-doc.org/en/master/>`_. The ``.github/workflows`` assume this documentation system is used when building and deploying the documentation to :program:`github pages`.
+
+If you replace the documentation system you will need to review and update:
+
+``.github/workflows/buid_and_release_docs.yml``
+  This is responsible for the release build of documentation and publishing to :program:`github pages`.
+``package.json``
+  Update (or remove) the ``serve:docs`` and ``devserve:docs`` script entries.
+``scripts``
+  Update (or remove) the scripts invoked from ``package.json``.
+
+.. rubric:: Footnotes
+
+.. [#F1] Well, at least something that understands Github actions and workflow format. Try `act <https://github.com/nektos/act>`_, this can be usefull for local testing of workflows. It is also the workflow system used by `Gitea <https://about.gitea.com/>`_ (if you fancy an alternative web-based repository host).

docs/developers/prerequisites.rst

@@ -0,0 +1,22 @@
+.. _prerequisites:
+Prerequisites
+=============
+
+``nodeJS``
+
+  This template is tested against ``modejs`` version 22.14.0.
+
+``pnpm``
+
+  The package manager of choice. (See :ref:`replace pnpm` if you object to efficiency.)
+
+``docker``
+
+  (And ``docker compose``---commonly bundled when you install Docker.)
+
+  * ``docker`` version v28+
+  * ``docker compose`` version v2.33+
+
+``git``
+
+  Pretty much any modern ``git``, at the time of writing I have v2.39.5 installed.

docs/developers/setup.rst

@@ -0,0 +1,52 @@
+Setup
+=====
+
+Once the :ref:`prerequisites` are installed setup is simple enough.
+
+.. code-block
+
+   git clone -depth 1 https://github.com/Mondarth..... project-name
+   cd project-name
+   rm -rf .git
+   git init
+   pnpm install
+   pnpm prepare
+
+Edit ``module.json`` and set:
+
+``id``
+  A unique id for the module. Use ``-`` instead of a space (and no spaces), lowercase.
+``title``
+  A string short title for the module. This will appear in on the Foundry Add-Modules page.
+``description``
+  A description of what the module does. Keep it short. This also appears on the Add-Module screen.
+``authors``
+  Porvide at least one Author entry.
+``compatibility``
+  Set which versions of Foundry this module is compatible.
+
+You may also need to set various other values in ``module.json`` (e.g. ``socket`` if your module uses ``socketlib``), but these will vary widely according to what your module does.
+
+If you use :program:`github` for your versioning and distribution then you can leave the following entries alone and the ``.github/workflows`` will maintain them for you. (Otherwise, see :ref:`replacing github`.)
+
+* ``url``
+* ``readme``
+* ``bugs``
+* ``changelog``
+* ``manifest``
+* ``download``
+
+
+Edit ``docs/conf.py`` and change:
+
+``project``
+  This will be the documentation's main title (and home page).
+``copyright``
+  holder of the copyright to the documenation.
+``author``
+  Who wrote the documentation.
+
+If using the provided :program:`github` setup the ``release`` will be maintained by the documentation build workflow.
+
+And you should be good to go.
+

docs/developers/why.rst

@@ -0,0 +1,43 @@
+Why ...
+=======
+
+... use ``pnpm``?
+-----------------
+
+``pnpm`` uses a cache and is more efficient than ``npm``.
+
+... use ``github``?
+-------------------
+
+It is pretty ubiquitous and virtually a standard for managing Foundry modules.
+
+... use ``zx`` for scripting?
+-----------------------------
+
+We have ``nodejs`` installed so may as well stick with javascript. It is also more platform independent.
+
+... use ``vite``?
+-----------------
+
+It provides nice tools (like an |HMR| development server) out of the box.
+
+... use ``vitest``?
+-------------------
+
+Clean, simple, flexible, and ties in to ``vite`` ecosystem.
+
+... use ``docker``?
+-------------------
+
+For ancillary tooling it provides a neat way to isolate from the host (so we can provide neat features without needing to have you install a load of stuff). It also provides a nicely isolated environment for running development Foundry VTT servers, which can also be used in more advances scenarios in ``.github/wormflows``.
+
+... document with Sphinx?
+-------------------------
+
+This is just my taste. I like the power and simplicity of ReStructured Text (more that Markdown but shallower learning curve than, for example, LaTeX). I also like the flexible output method from Sphinx. (See :ref:`replacing sphinx`)
+
+... all the ``svelte`` stuff?
+-----------------------------
+
+This module template assumes you will be using `svelte <https://svelte.dev>`_ for any UI (rather than the Foundry Handlebars). :program:`Svelte` is (|IMHO|) a more powerful, more reactive, yet simpler, UI framework. It plays nicely with ``vite`` and together they produce small modules. One can use a complete library, such as `TyphonJS <https://github.com/typhonjs-fvtt-lib>`_ (which attempts to replicate the Foundry API UI as Svelte components), or simply wrap standard Svelte by extending `ApplicationV2 <https://foundryvtt.com/api/v12/classes/foundry.applications.api.ApplicationV2.html>`_. Which is better depends on your objectives.
+

docs/developers/why_not.rst

@@ -0,0 +1,7 @@
+Why not...
+==========
+
+... use ``docker`` to isolate the whole development environment?
+----------------------------------------------------------------
+
+More trouble than it is worth. Although less of an issue than it used to be using docker in docker can be tricky. Similarly, individual developer IDE preferences can get messy when using docker development containers. It is simpler to use ``nodejs`` on the host and rely on ``pnpm`` for most of the build/runtime environment isolation.

docs/developers/zx_scripts.rst

@@ -0,0 +1,74 @@
+.. _zx scripts:
+``zx`` Scripts
+==============
+
+These scripts are utilities for use during development, build, and testing. They are not part of the final module.
+
+The Scripts
+-----------
+
+These scripts defer to `PDT <https://github.com/ulenarofmondarth/pdt>`_\ [#F2]_ if it is installed. Otherwise they offer limited capabilities aimed at providing single module development and test environments.
+
+foundryvtt
+~~~~~~~~~~
+
+Controls one or more local Foundry VTT instances.
+
+:program:`foundryvtt start`
+   Start the default Foundry VTT. If a previously stopped default instance exists this will restart it. If the instance is already running nothing is done.
+
+:program:`foundryvtt stop`
+   Stop the default Foundry VTT. If the instance is not running nothing is done.
+
+:program:`foundryvtt reset`
+   Reset (clear all data, so use with care) the default Foundry VTT. It the instance exists it is stopped (if running), the container is destroyed, and the data directory is destroyed.
+
+
+
+Configuring Scripts
+-------------------
+
+The easiest way to set the environment variables for these scripts is with a `'.env`` file in the root of your project. All environment variables specific to these scripts are prefixed with ``ZXS_`` (for 'ZX Script').
+
+You will find the defaults in ``.env``. These defaults will generally work well in a standalone module build environment\ [#F1]_. To override these it is recommended to create a ``.env.local`` specific to your development environment. You should not commit ``.env.local`` into :program:`git`.
+
+The general form of configuration environment variables is: ``ZXS_<hierarchical namespace>`` where the namespaces are delineated by ``_``.
+
+The configuration
+
+  
+
+.. code-block:: json
+
+   {
+     "docker": {
+        "main-vtt": {
+          "name": "foundry-vtt",
+          "ports": {
+            "vtt": {
+               "container": 8000,
+               "host": 8080
+              }
+            }
+          }
+        }
+
+     }
+   }
+
+is represented with the environment vairables
+
+.. code-block:: sh
+
+   ZXS_DOCKER_MAIN-VTT_NAME = "foundry-vtt"
+   ZXS_DOCKER_MAIN-VTT_PORTS_VTT_CONTAINER = 8000
+   ZXS_DOCKER_MAIN-VTT_PORTS_VTT_HOST = 8080
+
+.. note:: No attempt is made to represent an array in this schema. Instead an 'array' is represented as the values of an object, in the example neithes ``docker`` nor ``ports`` care about their keys, the script treats the values as a simple array.
+
+.. rubric:: Footnote
+
+.. [#F2] PDT offers a suite of tools to help with development and testing of Foundry modules.
+
+.. [#F1] If you are incorporating this module into a monorepo then you will need to rework a lot of the scripts and workflows. This is *way* beyond the scope of this text. Dealing with the defaults in ``.env`` is going to be the least of your issues.
+

docs/index.rst

@@ -0,0 +1,22 @@
+Module documentation
+====================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: For Developers:
+
+   developers/prerequisites.rst
+   developers/setup.rst
+   developers/zx_scripts.rst
+   developers/alternatives.rst
+   developers/why.rst
+   developers/why_not.rst

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=.
+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