Getting Started
===============

Suppose you are about to build a Python module or write documentation
for an existing one. This section demonstrates how to get started
with Waterloo Docstrings.

We use Sphinx as the primary documentation system to generate
human-readable documentation, and Waterloo's command-line tool
:wtrl_cmd:`waterlint` to produce machine-readable output from the original
Python docstrings.

If you are only interested in machine-readable documentation,
you may skip sections :ref:`section_sphinx`
and :ref:`section_building_human_readable_documentation`.

Setup Root Directory
--------------------

In the following sections, we refer to the project's root directory as ``${ROOT}``.
Navigate to this directory in your terminal before proceeding.

We use the placeholder name :wtrl_mod:`my_module` for the module to be documented
(and as a prefix for related files), and :wtrl_file:`my_module.py`
for the corresponding source file.

.. _section_venv:

Virtual Environment
-------------------

We recommend using a Python virtual environment for the initial setup.
This prevents upgrades of your system-wide installations of
:wtrl_lit:`pip`, :wtrl_lit:`sphinx`, and other packages, which may not
be desirable.

Create a Virtual Environment
............................

There is extensive documentation available for :wtrl_lit:`venv`,
but since it is straightforward to use, we briefly summarize
the basic steps here.

Make sure you are in your project directory, then run:

.. code-block:: bash

    python3 -m venv venv_wtrl

This creates a directory :wtrl_file:`venv_wtrl`
containing a standard Python installation.

Activate the Environment
........................

Run the activation command appropriate for your operating system and shell.


.. list-table:: Activation Commands
	:widths: 20 30 50
	:header-rows: 1

	* - Platform
	  - Shell
	  - Command
	* - **Unix** / **macOS**
	  - Bash / Zsh
	  - :wtrl_lit:`source venv_wtrl/bin/activate`
	* - 
	  - Fish
	  - :wtrl_lit:`source venv_wtrl/bin/activate.fish`
	* -
	  - csh/tcsh
	  - :wtrl_lit:`source venv_wtrl/bin/activate.csh`
	* - **Windows**
	  - PowerShell
	  - :wtrl_lit:`./venv_wtrl/Scripts/Activate.ps1`
	* - 
	  - Command Prompt
	  - :wtrl_lit:`venv_wtrl/Scripts/activate.bat`
	* - 
	  - Git Bash
	  - :wtrl_lit:`source venv_wtrl/Scripts/activate`

.. note::
	**Windows / PowerShell:**  
	If you encounter an execution policy error, allow script execution
	for the current session by running:

	``Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser``

Leave the environment using :wtrl_cmd:`deactivate`
when you are finished with this tutorial.

.. _section_sphinx:

Install Sphinx
--------------

You have likely already installed Sphinx. However, if you are working
inside the virtual environment recommended above, you need to install
it there as well.

First, ensure that you are using the latest version of pip:

.. code-block:: bash

	python3 -m pip install --upgrade pip

.. note::
	If :wtrl_cmd:`python3 -m pip` is not available inside the activated
	environment, bootstrap pip first:

	.. code-block:: bash

		python3 -m ensurepip --upgrade

Then install Sphinx and any extensions required for your project:

.. code-block:: bash

	python3 -m pip install sphinx

You are still in the project's root directory.
Create a directory for the human-readable documentation:

.. code-block:: bash

	mkdir doc
	cd doc

Initialize a Sphinx project, for example using :wtrl_cmd:`sphinx-quickstart`:

.. code-block:: bash

	sphinx-quickstart

	> Separate source and build directories (y/n) [n]: y
	> Project name: My-Project
	> Author name(s): My-Name
	> Project release []: 0.0.1

Waterloo is currently not multilingual, so we use English as the project language:

.. code-block:: bash

	> Project language [en]:

Build the documentation to verify the setup:

.. code-block:: bash

	make clean && make html

Open the generated documentation in your browser
(replace :wtrl_var:`${ROOT}` with your project's root directory):

:wtrl_file:`file://`:wtrl_var:`${ROOT}`:wtrl_file:`/doc/build/html/index.html`

.. _section_waterloo_docstrings:

Waterloo Docstrings
-------------------

Install Waterloo Docstrings
...........................

If you have not done so already, update :wtrl_lit:`pip`:

.. code-block:: bash

	python3 -m pip install --upgrade pip

Install Waterloo from PyPI:

.. code-block:: bash

	python3 -m pip install sdv-doc-waterloo

If you want to work from the current source tree, install from GitHub via HTTPS:

.. code-block:: bash

	python3 -m pip install git+https://github.com/uwe-at-sdv/sdv_doc_waterloo.git

Add the extension to :wtrl_file:`${ROOT}/doc/source/conf.py`:

.. code-block:: python

	# -- General configuration -------------------------------------

	extensions = [
		# other extensions
		"sdv.doc.waterloo.docitem_sphinx",
	]

Configure the path to your project sources:

.. code-block:: python

	# -- Path setup ------------------------------------------------

	# If your modules are located outside the documentation directory,
	# add their paths here. Use os.path.abspath to convert relative
	# paths to absolute ones if necessary.
	import sys

	ROOT = "/path/to/my/project"
	sys.path.insert(0, ROOT)

Adding a Waterloo Docstring
............................

Insert the following example docstring at the top of your module
source file :wtrl_file:`my_module.py`.

Indentation may use either a tab character or four spaces.
In this example, four spaces are used for convenience.

.. code-block:: python

    r"""
    Preamble:
        profile:
            module
        normative_sections:
            Contract
    Contract:
        general:
            |Must| serve as an example for a Waterloo docstring.
    """

The next step is important and should be applied to every
docstring you write: validate it formally.

While the Waterloo Sphinx extension can detect structural
errors, the linter provides more detailed and clearer diagnostics.

.. code-block:: bash

	waterlint validate --basedir . --obj my_module

.. _section_building_human_readable_documentation:

Building a Human-Readable Documentation
........................................

To see how Waterloo integrates with Sphinx, add the following
directive to a source file, for example :wtrl_file:`index.rst`
(for testing purposes):

.. code-block:: rst

	.. wtrl_autodoc_module:: my_module

Build the documentation:

.. code-block:: bash

	make clean && make html

In your browser, you should now see a compact and structured
representation of the module docstring.

Other object types (such as classes and functions) can be added
in the same way using the corresponding directives.

Building a Machine-Readable Documentation
.........................................

As outlined in the introduction, LLMs can process the original
Waterloo docstrings directly. However, JSON is often preferred
because it is not indentation-based and can be validated using
established JSON schema mechanisms.

Create a directory for the JSON output. Since Waterloo Docstrings
is a relatively new project (2026), no established best practice
exists yet. We recommend naming the directory "doc-json" so that
AI agents can locate it easily. Navigate back to your project
directory and run:

.. code-block:: bash

	mkdir doc-json

Render the module documentation in JSON format:

.. code-block:: bash

	waterlint render-json --basedir . --obj my_module --out-dir doc-json

Validate the generated JSON file:

.. code-block:: bash

	waterlint validate-json --in doc-json/my_module.wtrl.core.rfc-2119.json

If no error message is shown and the exit code is 0,
the JSON output is valid.

To list the installed Waterloo JSON schemas, run:

.. code-block:: bash

    waterlint list-schemas

Final Remarks
-------------

This section outlines the minimal steps required to integrate
Waterloo Docstrings into a project.

Further examples are provided in
:ref:`chapter_examples` and :ref:`chapter_examples_minimax`.

The formal specification of the format is given in
:ref:`chapter_format`.