From d67eab8e30e1305e91676caae3646d8f39a93e15 Mon Sep 17 00:00:00 2001 From: Kevin Burnett <18027+burnettk@users.noreply.github.com> Date: Fri, 10 Jan 2025 01:00:18 +0000 Subject: [PATCH] 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 --- docs/explanation/dev/index.md | 50 +++++-------------- docs/explanation/dev/overview.md | 39 +++++++++++++++ docs/explanation/index.md | 25 ++-------- .../learn_basics.md | 0 docs/fullindex.md | 14 ++++++ docs/how_to_guides/building_diagrams/bpmn.md | 2 +- docs/how_to_guides/building_diagrams/index.md | 8 ++- .../user_tasks_and_forms.md | 0 docs/how_to_guides/deployment/index.md | 2 +- docs/how_to_guides/index.md | 11 ++-- docs/how_to_guides/running_server_locally.md | 11 ++-- docs/how_to_guides/welcome_messages.md | 3 +- docs/index.md | 2 +- docs/reference/bpmn/index.md | 22 ++++++++ .../documentation.md | 8 +-- docs/reference/index.md | 25 ++-------- 16 files changed, 120 insertions(+), 102 deletions(-) create mode 100644 docs/explanation/dev/overview.md rename docs/{how_to_guides/building_diagrams => explanation}/learn_basics.md (100%) create mode 100644 docs/fullindex.md rename docs/{reference/bpmn => how_to_guides/building_diagrams}/user_tasks_and_forms.md (100%) create mode 100644 docs/reference/bpmn/index.md rename docs/{how_to_guides => reference}/documentation.md (93%) diff --git a/docs/explanation/dev/index.md b/docs/explanation/dev/index.md index 20586d546..6028ff44d 100644 --- 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 new file mode 100644 index 000000000..bccb2a4fb --- /dev/null +++ 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 index f2bfdda2e..c6619ca45 100644 --- 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/docs/how_to_guides/building_diagrams/learn_basics.md b/docs/explanation/learn_basics.md similarity index 100% rename from docs/how_to_guides/building_diagrams/learn_basics.md rename to docs/explanation/learn_basics.md diff --git a/docs/fullindex.md b/docs/fullindex.md new file mode 100644 index 000000000..3aefec41f --- /dev/null +++ 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 index 179152953..1541bef75 100644 --- 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 index 891a30dd0..dc2fa3ab2 100644 --- 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 b/docs/how_to_guides/building_diagrams/user_tasks_and_forms.md similarity index 100% rename from docs/reference/bpmn/user_tasks_and_forms.md rename to docs/how_to_guides/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 index 7cf1896bd..ef9812d5c 100644 --- 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 index f7e99e3ef..4d328ffb0 100644 --- 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 index b79640729..2fbdf2b9b 100644 --- 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 index 13c150ec2..5ae2112d6 100644 --- 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 index 61eea06c2..d7dd7050f 100644 --- 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 new file mode 100644 index 000000000..15f460711 --- /dev/null +++ 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 b/docs/reference/documentation.md similarity index 93% rename from docs/how_to_guides/documentation.md rename to docs/reference/documentation.md index 3e9fdfe67..278b14a68 100644 --- a/docs/how_to_guides/documentation.md +++ b/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: ```{tags} tutorial diff --git a/docs/reference/index.md b/docs/reference/index.md index d55558718..8ea444086 100644 --- 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 ```