Reorg docs (#2215)

* docs: Update the documentation structure in the todo list * add full index * titlesonly * move documentation to reference * docs: Nest BPMN elements under a new "Elements of BPMN" section * not hidden * docs: Mark first three TODO items as completed * fix: Uncheck incorrect checkboxes in todo.md * move * move building diagrams to own section * renames * docs * move to explanation * explanation * reorder * move forms * rm todo * typo --------- Co-authored-by: burnettk <[email protected]>
sartography · Jan 10, 2025 · d67eab8 · d67eab8
1 parent 092fe39
commit d67eab8
Show file tree

Hide file tree

Showing 16 changed files with 120 additions and 102 deletions.
diff --git a/docs/explanation/dev/index.md b/docs/explanation/dev/index.md
@@ -1,38 +1,14 @@
-# Technical Overview
-
-## Components
-
-```mermaid
-graph TD
-subgraph spiff-arena
-    Backend
-    Frontend
-end
-subgraph Backend
-    subgraph SpiffWorkflow lib
-    end
-end
-subgraph Frontend
-    subgraph bpmn-js-spiffworkflow lib
-    end
-end
-Frontend -- uses REST API --> Backend
-Backend -- delegates to --> C
-Backend -- persists to --> DB
-DB[(mysql/postgres)]
-C[Connector Proxy]
-```
-
-SpiffArena is a system that allows users to build and execute BPMN diagrams.
-It is composed of three applications, [spiffworkflow-frontend](frontend), [spiffworkflow-backend](backend), and, optionally, a [connector proxy](connector_proxy).
-
-## Source code layout
-
-From a source code perspective, there are three repositories that may be of interest:
-
-* [spiff-arena](https://github.com/sartography/spiff-arena) - Includes spiffworkflow-frontend, spiffworkflow-backend, and connector-proxy-demo.
-* [SpiffWorkflow](https://github.com/sartography/SpiffWorkflow) - The core SpiffWorkflow library, 10 years old, Python, awesome, [well-documented](https://spiffworkflow.readthedocs.io/).
-* [bpmn-js-spiffworkflow](https://github.com/sartography/bpmn-js-spiffworkflow) - The frontend library that extends bpmn-js to work with SpiffWorkflow.
-
-```{tags} reference, dev_docs
+# Technical Docs
+
+```{toctree}
+:caption: Technical Docs
+:maxdepth: 1
+overview
+setup
+backend
+frontend
+connector_proxy
+how_to_build_a_connector
+extensions
+process
 ```
diff --git a/docs/explanation/dev/overview.md b/docs/explanation/dev/overview.md
@@ -0,0 +1,39 @@
+# Technical Overview
+
+## Components
+
+```mermaid
+graph TD
+subgraph spiff-arena
+    Backend
+    Frontend
+end
+subgraph Backend
+    subgraph SpiffWorkflow lib
+    end
+end
+subgraph Frontend
+    subgraph bpmn-js-spiffworkflow lib
+    end
+end
+Frontend -- uses REST API --> Backend
+Backend -- delegates to --> C
+Backend -- persists to --> DB
+DB[(mysql/postgres)]
+C[Connector Proxy]
+```
+
+SpiffArena is a system that allows users to build and execute BPMN diagrams.
+It is composed of three applications, [spiffworkflow-frontend](frontend), [spiffworkflow-backend](backend), and, optionally, a [connector proxy](connector_proxy).
+
+## Source code layout
+
+From a source code perspective, there are three repositories that may be of interest:
+
+- [spiff-arena](https://github.com/sartography/spiff-arena) - Includes spiffworkflow-frontend, spiffworkflow-backend, and connector-proxy-demo.
+- [SpiffWorkflow](https://github.com/sartography/SpiffWorkflow) - The core SpiffWorkflow library, 10 years old, Python, awesome, [well-documented](https://spiffworkflow.readthedocs.io/).
+- [bpmn-js-spiffworkflow](https://github.com/sartography/bpmn-js-spiffworkflow) - The frontend library that extends bpmn-js to work with SpiffWorkflow.
+
+```{tags} reference, dev_docs
+
+```
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -4,24 +4,9 @@ In this section, you will find explanations of key concepts and processes in Spi
 
 ```{toctree}
 :maxdepth: 1
-articles.md
-```
-
-```{toctree}
-:caption: Debugging Diagrams
-:maxdepth: 1
-process_error_handling.md
-```
-
-```{toctree}
-:caption: Technical Docs
-:maxdepth: 1
-dev/index.md
-dev/setup.md
-dev/backend.md
-dev/frontend.md
-dev/connector_proxy.md
-dev/how_to_build_a_connector.md
-dev/extensions.md
-dev/process.md
+:titlesonly:
+articles
+learn_basics
+dev/index
+process_error_handling
 ```
diff --git a/..._guides/building_diagrams/learn_basics.md → docs/explanation/learn_basics.md b/..._guides/building_diagrams/learn_basics.md → docs/explanation/learn_basics.md
diff --git a/docs/fullindex.md b/docs/fullindex.md
@@ -0,0 +1,14 @@
+---
+orphan: true
+---
+
+# Full Index
+
+```{toctree}
+:titlesonly:
+
+tutorials/index
+how_to_guides/index
+reference/index
+explanation/index
+```
diff --git a/docs/how_to_guides/building_diagrams/bpmn.md b/docs/how_to_guides/building_diagrams/bpmn.md
@@ -6,7 +6,7 @@ Here are some helpful tips to guide you through the process and create effective
 **Understand BPMN Symbols:**
 Begin by thoroughly understanding the meaning and usage of each BPMN symbol.
 This will ensure that you use the symbols correctly to represent the various elements of your business process.
-Refer to the [Learn Basics](/reference/glossary.md) section to learn more about each symbol.
+Refer to the [Learn Basics](/explanation/learn_basics) section to learn more about each symbol.
 
 Grouping them together can create a mind map that's easy to remember.
 

diff --git a/docs/how_to_guides/building_diagrams/index.md b/docs/how_to_guides/building_diagrams/index.md
@@ -1,7 +1,11 @@
-# All Building Diagrams How-to Guides
+# How to Build Diagrams
 
 ```{toctree}
 :maxdepth: 1
+bpmn
+user_tasks_and_forms
+displaying_content
+builtin_examples
 executable_non_executable
-bpmn_unit_tests.md
+bpmn_unit_tests
 ```
diff --git a/docs/reference/bpmn/user_tasks_and_forms.md → ...building_diagrams/user_tasks_and_forms.md b/docs/reference/bpmn/user_tasks_and_forms.md → ...building_diagrams/user_tasks_and_forms.md
diff --git a/docs/how_to_guides/deployment/index.md b/docs/how_to_guides/deployment/index.md
@@ -1,4 +1,4 @@
-# Deployment How-to Guides
+# How to Deploy
 
 ```{toctree}
 :maxdepth: 1

diff --git a/docs/how_to_guides/index.md b/docs/how_to_guides/index.md
@@ -4,22 +4,17 @@
 
 ```{toctree}
 :maxdepth: 1
-:caption: General How-to Guides
-custom_process_metadata
-documentation
+:caption: How-to Guides
+building_diagrams/index
 manage_processes
 welcome_messages
+custom_process_metadata
 running_server_locally
 ```
 
 ```{toctree}
 :maxdepth: 1
 :caption: Building Diagrams
-building_diagrams/index.md
-building_diagrams/learn_basics.md
-building_diagrams/bpmn.md
-building_diagrams/displaying_content.md
-building_diagrams/builtin_examples.md
 ```
 
 ```{toctree}

diff --git a/docs/how_to_guides/running_server_locally.md b/docs/how_to_guides/running_server_locally.md
@@ -1,4 +1,4 @@
-# Troubleshooting: Running Server Locally
+# Troubleshooting Locally
 
 When setting up the SpiffWorkflow backend project locally, you might encounter issues related to the `sample-process-models` directory.
 This documentation aims to address those concerns.
@@ -29,9 +29,9 @@ If you prefer not to use the `sample-process-models` directory or want to start
 
 - Run the following command with the path to your chosen repository:
 
-   ```
-   SPIFFWORKFLOW_BACKEND_BPMN_SPEC_ABSOLUTE_DIR=/path/to/any/git/repo ./bin/run_server_locally
-   ```
+  ```
+  SPIFFWORKFLOW_BACKEND_BPMN_SPEC_ABSOLUTE_DIR=/path/to/any/git/repo ./bin/run_server_locally
+  ```
 
 ### 3. Use Docker Compose
 
@@ -55,7 +55,7 @@ You may need to install additional system dependencies:
 
 One person decided that mysqlclient and psycopg2 were more trouble than they were worth and removed them from the pyproject.toml, opting instead to run `poetry add pymysql`.
 If you are using mysql, psycopg2 is not necessary, and pymysql is a pure Python implementation of the MySQL client library.
-In that case, Python won't recognize MySQLdb as a module, so after the above installs (which you would do pre-Poetry), add these lines to __init__.py in the backend project:
+In that case, Python won't recognize MySQLdb as a module, so after the above installs (which you would do pre-Poetry), add these lines to `__init__.py` in the backend project:
 
 ```python
 import pymysql
@@ -76,4 +76,5 @@ Whether you choose to clone the `sample-process-models` repository, use a differ
 If you encounter further issues, always refer back to the repository's README or seek assistance from our Discord community.
 
 ```{tags} how_to_guide
+
 ```
diff --git a/docs/how_to_guides/welcome_messages.md b/docs/how_to_guides/welcome_messages.md
@@ -1,4 +1,4 @@
-# Welcome Messages in SpiffWorkflow
+# Welcome Messages
 
 ## Introduction
 
@@ -40,4 +40,5 @@ Once you've updated the welcome message, it will be displayed prominently on the
 The message will be positioned in a way that it's one of the first things users see, ensuring they receive the intended greeting every time they access the platform.
 
 ```{tags} how_to_guide
+
 ```
diff --git a/docs/index.md b/docs/index.md
@@ -18,8 +18,8 @@
 
 tutorials/index
 how_to_guides/index
-reference/index
 explanation/index
+reference/index
 ```
 
 ## [Tutorials](tutorials/index)

diff --git a/docs/reference/bpmn/index.md b/docs/reference/bpmn/index.md
@@ -0,0 +1,22 @@
+# Elements of BPMN
+
+This section provides detailed information about the various elements used in Business Process Model and Notation (BPMN) diagrams within SpiffWorkflow.
+
+```{toctree}
+:maxdepth: 1
+gateways.md
+events.md
+message_events.md
+signal_events.md
+timer_events.md
+escalation_events.md
+conditional_events.md
+error_events.md
+Script_Tasks.md
+service_tasks.md
+sub-processes_and_call_activities.md
+data.md
+multiinstance.md
+dmn.md
+pools_and_lanes.md
+```
diff --git a/docs/how_to_guides/documentation.md → docs/reference/documentation.md b/docs/how_to_guides/documentation.md → docs/reference/documentation.md
@@ -1,15 +1,15 @@
 # How to Contribute to the Documentation
 
-This documentation is currently hosted live at [Spiff-Arena's ReadTheDocs](https://spiff-arena.readthedocs.io/en/latest/).
+The spiff-arena documentation is currently hosted live at [ReadTheDocs](https://spiff-arena.readthedocs.io/en/latest/).
 
-Please set aside a couple of hours to work through this, as getting this set up correctly once is 10,000 times better than having problems every day for the rest of your life.
+If you intend to edit the docs on an ongoing basis, please set aside a couple of hours to work through this guide, as getting this set up correctly once is 10,000 times better than having problems every day for the rest of your life.
 
 ## Our Methodology
 
 The methodology we are following is known as ["Docs as Code"](https://www.writethedocs.org/guide/docs-as-code/).
 
 This means using the same tools and processes that software developers use for writing code to write the documentation for code.
-In following this methodology, you will have to pick up some tools you haven't had to use before (Git, Sphinx).
+In following this methodology, you may have to pick up some tools you haven't had to use before (Git, Sphinx).
 Why would a technical writer need to learn these software engineering tools?
 I'll never make the case as well as an article by [Tom Johnson](https://idratherbewriting.com/trends/trends-to-follow-or-forget-docs-as-code.html).
 
@@ -154,7 +154,7 @@ A `.markdownlint.jsonc` file has been added that configures the same markdownlin
 ## Doc Philosphy
 
 We try to use [Diátaxis](https://diataxis.fr/).
-This is also highly related: https://docsfordevelopers.com/
+This is also highly related: <https://docsfordevelopers.com/>
 
 ```{tags} tutorial
 

diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -4,29 +4,10 @@ The Reference section contains detailed information about SpiffWorkflow's compon
 
 ```{toctree}
 :maxdepth: 1
+bpmn/index
 glossary
 FAQ.md
 wish_list
-permission_url.md
-```
-
-```{toctree}
-:maxdepth: 1
-:caption: Elements of BPMN
-bpmn/user_tasks_and_forms.md
-bpmn/gateways.md
-bpmn/events.md
-bpmn/message_events.md
-bpmn/signal_events.md
-bpmn/timer_events.md
-bpmn/escalation_events.md
-bpmn/conditional_events.md
-bpmn/error_events.md
-bpmn/Script_Tasks.md
-bpmn/service_tasks.md
-bpmn/sub-processes_and_call_activities.md
-bpmn/data.md
-bpmn/multiinstance.md
-bpmn/dmn.md
-bpmn/pools_and_lanes.md
+permission_url
+documentation
 ```