Make documentation easier for people just getting started

Author: cmutel

docs-src/common-workflows.md

@@ -21,6 +21,17 @@ Where:
 * `host` is the URL that `py-semantic-taxonomy` is running at, e.g. "http://localhost:8000" if running locally
 * `sample` is a boolean flag on whether only a sample of the available data should be imported. The full import takes more than an hour.
 
+If you are testing locally using the default Docker containers for Postgres and Typesense, then the `CombinedNomenclatureLoader` can take these values:
+
+```python
+CombinedNomenclatureLoader(
+    year=2024,
+    api_key="abc123",  # Default API key; adjust if needed
+    host="http://127.0.0.1:8000",  # Default Uvicorn port; adjust if needed
+    sample=True
+).write()
+```
+
 ## Creating a new taxonomy
 
 PyST stores concept schemes, concepts, and relationships between concepts all in different places, so the creation of these objects needs to happen in a defined order:

docs-src/index.md

@@ -4,6 +4,8 @@ PyST is opinionated server software for creating, maintaining, and publishing [S
 
 * [API docs](https://docs.pyst.dev/api/), [OpenAPI 3.1 JSON](https://docs.pyst.dev/api/openapi.json), [OpenAPI 3.1 YAML](https://docs.pyst.dev/api/openapi.yaml)
 * [GitHub repo](https://github.com/cauldron/py-semantic-taxonomy/)
+* [Client library](https://github.com/cauldron/pyst-client/)
+* [Client library usage guide](https://github.com/cauldron/pyst-client/blob/main/pyst_client/example/Simple%20client%20library%20guide.ipynb)
 * [Example notebook](https://github.com/cauldron/py-semantic-taxonomy/blob/main/examples/PyST%20basic%20demo.ipynb)
 
 PyST was built and is maintained by [Cauldron Solutions](https://www.cauldron.ch/).
@@ -16,6 +18,17 @@ PyST was built and is maintained by [Cauldron Solutions](https://www.cauldron.ch
 * Install and configure [Typesense](https://typesense.org/)
 * `pip install py-semantic-taxonomy`
 
+If you just want to try our the software, and have Docker installed on your machine, you can run Postgres and Typesense in containers using the scripts in the `scripts` directory, i.e.:
+
+* `python scripts/start_postgres_container.py`
+* `python scripts/start_typesense_container.py`
+
+These scripts will give you the values of the environment variables needed for step 2. Note that you will still need to make up your own `PyST_auth_token` setting and make sure it is set correctly, i.e.:
+
+```console
+export PyST_auth_token="supersecret"
+```
+
 2\. Configure required software
 
 The following parameters must be either specified as environment variables, or given in the file `pyst-config.env`.
@@ -50,8 +63,16 @@ uvicorn.run(
 )
 ```
 
+If you are using the default ASGI app runner and configuration options, you can also do:
+
+```console
+python <pyst-source-directory>/src/py_semantic_taxonomy/app.py
+```
+
 4\. Add data
 
+See [common workflows](common-workflows.md) for a guide on adding example data.
+
 ## Why New Software?
 
 There are a number of great projects for browsing SKOS taxonomies already, including:

docs/api/index.html

@@ -1535,6 +1535,7 @@
             ]
           }
         },
+        "additionalProperties": true,
         "type": "object",
         "required": [
           "@id",

docs/api/openapi.json

@@ -985,6 +985,7 @@ components:
           description: https://rdf-vocabulary.ddialliance.org/xkos.html#correspondences
           example:
           - '@id': http://data.europa.eu/xsp/cn2024/010011000090
+      additionalProperties: true
       type: object
       required:
       - '@id'

docs/api/openapi.yaml

@@ -528,6 +528,14 @@ <h2 id="importing-the-combined-nomenclature-codes">Importing the Combined Nomenc
 <li><code>host</code> is the URL that <code>py-semantic-taxonomy</code> is running at, e.g. "http://localhost:8000" if running locally</li>
 <li><code>sample</code> is a boolean flag on whether only a sample of the available data should be imported. The full import takes more than an hour.</li>
 </ul>
+<p>If you are testing locally using the default Docker containers for Postgres and Typesense, then the <code>CombinedNomenclatureLoader</code> can take these values:</p>
+<div class="highlight"><pre><span></span><code><span class="n">CombinedNomenclatureLoader</span><span class="p">(</span>
+    <span class="n">year</span><span class="o">=</span><span class="mi">2024</span><span class="p">,</span>
+    <span class="n">api_key</span><span class="o">=</span><span class="s2">&quot;abc123&quot;</span><span class="p">,</span>  <span class="c1"># Default API key; adjust if needed</span>
+    <span class="n">host</span><span class="o">=</span><span class="s2">&quot;http://127.0.0.1:8000&quot;</span><span class="p">,</span>  <span class="c1"># Default Uvicorn port; adjust if needed</span>
+    <span class="n">sample</span><span class="o">=</span><span class="kc">True</span>
+<span class="p">)</span><span class="o">.</span><span class="n">write</span><span class="p">()</span>
+</code></pre></div>
 <h2 id="creating-a-new-taxonomy">Creating a new taxonomy<a class="headerlink" href="#creating-a-new-taxonomy" title="Permanent link">#</a></h2>
 <p>PyST stores concept schemes, concepts, and relationships between concepts all in different places, so the creation of these objects needs to happen in a defined order:</p>
 <ul>

docs/common-workflows/index.html

@@ -477,6 +477,8 @@ <h1 id="pyst-py-semantic-taxonomy">PyST (py-semantic-taxonomy)<a class="headerli
 <ul>
 <li><a href="https://docs.pyst.dev/api/">API docs</a>, <a href="https://docs.pyst.dev/api/openapi.json">OpenAPI 3.1 JSON</a>, <a href="https://docs.pyst.dev/api/openapi.yaml">OpenAPI 3.1 YAML</a></li>
 <li><a href="https://github.com/cauldron/py-semantic-taxonomy/">GitHub repo</a></li>
+<li><a href="https://github.com/cauldron/pyst-client/">Client library</a></li>
+<li><a href="https://github.com/cauldron/pyst-client/blob/main/pyst_client/example/Simple%20client%20library%20guide.ipynb">Client library usage guide</a></li>
 <li><a href="https://github.com/cauldron/py-semantic-taxonomy/blob/main/examples/PyST%20basic%20demo.ipynb">Example notebook</a></li>
 </ul>
 <p>PyST was built and is maintained by <a href="https://www.cauldron.ch/">Cauldron Solutions</a>.</p>
@@ -487,6 +489,14 @@ <h2 id="quickstart">Quickstart<a class="headerlink" href="#quickstart" title="Pe
 <li>Install and configure <a href="https://typesense.org/">Typesense</a></li>
 <li><code>pip install py-semantic-taxonomy</code></li>
 </ul>
+<p>If you just want to try our the software, and have Docker installed on your machine, you can run Postgres and Typesense in containers using the scripts in the <code>scripts</code> directory, i.e.:</p>
+<ul>
+<li><code>python scripts/start_postgres_container.py</code></li>
+<li><code>python scripts/start_typesense_container.py</code></li>
+</ul>
+<p>These scripts will give you the values of the environment variables needed for step 2. Note that you will still need to make up your own <code>PyST_auth_token</code> setting and make sure it is set correctly, i.e.:</p>
+<div class="highlight"><pre><span></span><code><span class="go">export PyST_auth_token=&quot;supersecret&quot;</span>
+</code></pre></div>
 <p>2. Configure required software</p>
 <p>The following parameters must be either specified as environment variables, or given in the file <code>pyst-config.env</code>.</p>
 <div class="admonition note">
@@ -516,7 +526,11 @@ <h2 id="quickstart">Quickstart<a class="headerlink" href="#quickstart" title="Pe
     <span class="n">log_level</span><span class="o">=</span><span class="s2">&quot;warning&quot;</span><span class="p">,</span>
 <span class="p">)</span>
 </code></pre></div>
+<p>If you are using the default ASGI app runner and configuration options, you can also do:</p>
+<div class="highlight"><pre><span></span><code><span class="go">python &lt;pyst-source-directory&gt;/src/py_semantic_taxonomy/app.py</span>
+</code></pre></div>
 <p>4. Add data</p>
+<p>See <a href="common-workflows/">common workflows</a> for a guide on adding example data.</p>
 <h2 id="why-new-software">Why New Software?<a class="headerlink" href="#why-new-software" title="Permanent link">#</a></h2>
 <p>There are a number of great projects for browsing SKOS taxonomies already, including:</p>
 <ul>

docs/index.html

@@ -2,22 +2,22 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://docs.pyst.dev/</loc>
-         <lastmod>2025-05-06</lastmod>
+         <lastmod>2025-06-05</lastmod>
     </url>
     <url>
          <loc>https://docs.pyst.dev/architecture/</loc>
-         <lastmod>2025-05-06</lastmod>
+         <lastmod>2025-06-05</lastmod>
     </url>
     <url>
          <loc>https://docs.pyst.dev/common-workflows/</loc>
-         <lastmod>2025-05-06</lastmod>
+         <lastmod>2025-06-05</lastmod>
     </url>
     <url>
          <loc>https://docs.pyst.dev/data-model/</loc>
-         <lastmod>2025-05-06</lastmod>
+         <lastmod>2025-06-05</lastmod>
     </url>
     <url>
          <loc>https://docs.pyst.dev/development/</loc>
-         <lastmod>2025-05-06</lastmod>
+         <lastmod>2025-06-05</lastmod>
     </url>
 </urlset>