Reorg and Ros2 Humble

README.md

@@ -80,6 +80,8 @@
 
 ## Workflow for publishing OutdoorNav User Manual updates
 
+<details>
+
 The OutdoorNav User Manual is a "versioned" document, which means that a snapshot of the content is
 made to align with a release. This allows users to access version-specific copies of the
 documentation.
@@ -88,7 +90,13 @@ documentation.
 
 During the development phase, follow steps 1-10 of the workflow above. Note that the updates will not affect
 the default view of the user manual, only the "next" version of the manual
-(eg. http://docs.clearpathrobotics.com/docs_outdoornav_user_manual/next/index).
+(eg. http://docs.clearpathrobotics.com/docs_outdoornav_user_manual/next/index). You can enable the visibility of the "next" version by setting
+
+```
+includeCurrentVersion: true,
+```
+
+in `docusaurus.config.js` alongside `id: "outdoornav_user_manual",` section. Ensure to reset this to false before releasing the changes.
 
 ### Release Phase
 
@@ -99,22 +107,98 @@ When it is time to publish a numbered release of the user manual:
 
         npm run docusaurus docs:version:outdoornav_user_manual <new_version>
 
-3.  Update /docs/software/navigation_packages.mdx to:
-    - Update the version number for the "Latest".
-    - Add an entry for the previous release.
-4.  Update /static/versions.js to update the outdoornav version to match the GitHub tag.
-5.  Build and test the changes (see steps 4-8 from the standard workflow above).
-6.  When ready, publish your branch on GitHub, and submit a Pull Request to merge your changes into the _development_ branch.
+3.  Update /static/versions.js to update the outdoornav version to match the GitHub tag.
+4.  Build and test the changes (see steps 4-8 from the standard workflow above).
+5.  When ready, publish your branch on GitHub, and submit a Pull Request to merge your changes into the _development_ branch.
     Be sure to include the updates to the following:
     - outdoornav_user_manual_versioned_docs/
     - outdoornav_user_manual_versioned_sidebars/
     - outdoornav_user_manual_versions.json
 
-## Workflow for publishing OutdoorNav User Manual updates
+</details>
+
+## Workflow for publishing IndoorNav User Manual updates
+
+<details>
 
 Follow the steps for the OutdoorNav User Manual workflow above, replacing
 **outdoornav** with **indoornav**.
 
+</details>
+
+## Workflow for publishing Robots / ROS User Manual updates
+
+<details>
+
+The Robots / ROS sections of the website are a "versioned" document called `docs`, which means that a snapshot of the content is
+made to align with each ROS version. This allows users to access version-specific copies of the
+documentation.
+
+### Maintenance Phase (For Existing Version)
+
+Follow steps 1-10 from [above](#workflow-for-making-updates). However, all changes will be made to the files within `docs_versioned_docs/` for the particular version that needs to be changed. E.g. any changes to the ROS 2 Humble documentation would be made to the files within `docs_versioned_docs/version-ros2humble/`.
+
+### Development Phase (For New Version)
+
+Start by following step 1 & 2 [above](#workflow-for-making-updates).
+
+Next, to start the development of a new version, the latest released version of the documentation must be copied over into the `docs/` folder.
+
+For Example, for making a new release after humble, the contents of `docs_versioned_docs/version-ros2humble/` would be copied to replace the contents of `docs/`.
+
+Continue through to step 10 of the workflow above. Note that the updates will not affect
+the default view of the user manual, only the "next" version of the manual
+(eg. http://docs.clearpathrobotics.com/docs_outdoornav_user_manual/next/index). You can enable the visibility of the "next" version by setting
+
+```
+includeCurrentVersion: true,
+```
+
+in `docusaurus.config.js` alongside `id: "docs",`. Ensure to reset this to false before releasing the changes.
+
+Once complete, continue to the release phase.
+
+> **Note**
+> The documentation includes unversioned mdx components from `components/` and versioned components from `docs/components/`. If versioning needs to be added move the component into the versioned folder for each version and remap the imports (using relative links).
+
+### Release Phase (For New Version)
+
+When it is time to publish a new version of the manual:
+
+1.  After developing the changes, run the versioning command, where _new_version_ is aligned with the corresponding software release:
+
+        npm run docusaurus docs:version:docs <new_version>
+
+    where the `<new_version>` has no spaces or dashes (E.g. for ROS 2 Humble the version should be set as `ros2humble`)
+
+2.  Update the `docusaurus.config.js` file, adding an entry within versions to map the version name to the display label.
+
+```js
+  versions: {
+    ros2humble: {
+      label: 'ROS 2 Humble',
+    },
+    ros1noetic: {
+      label: 'ROS 1 Noetic',
+    }
+  },
+```
+
+3. Ensure that the "next" version is disabled in the following line in the config:
+
+```
+includeCurrentVersion: false,
+```
+
+4.  Build and test the changes (see steps 4-8 from the standard workflow above).
+5.  When ready, publish your branch on GitHub, and submit a Pull Request to merge your changes into the _development_ branch.
+    Be sure to include the updates to the following:
+    - docs_versioned_docs/
+    - docs_versioned_sidebars/
+    - docs_versions.json
+
+</details>
+
 ## How should I write pages?
 
 1.  Refer to [Markdown's guide](https://www.markdownguide.org/basic-syntax/) for syntax
@@ -142,18 +226,22 @@ This helps User's know where they downloaded the file from later, as the asset i
 
         /docs
 
-2.  Markdown component, like a section to be reused in multiple pages
+2.  Markdown component, like a section to be reused in multiple pages (unversioned)
 
         /components
 
-3.  Images
+3.  Unversioned Images
 
         /static/img
 
 4.  PDFs and similar customer facing files
 
         /static/assets
 
+5.  Versioned Images
+
+    In an `img/` folder next to the markdown files where it will be used.
+
 ## How does the deployed website get updated?
 
 We have this site deployed on _AWS Amplify_.
@@ -212,6 +300,12 @@ The list below are not strict rules, but are considered good practice to keep im
 
     Note: icons, logos, and symbols that are part of the physical product are exempt from this suggestion.
 
+## Links and Imports
+
+All links to, or imports of versioned elements (images, markdown files etc.) must be referred to using relative links (`./img/image-name.png`). These versioned pages will be moved together and ensures that the correct version is used.
+
+All links to, or imports of unversioned static elements must be referred to using absolute paths (`/static/img/image-name.png`). This allows these assets to be found irrelevant of the location of the particular page.
+
 ## SolidWorks image exports
 
 1.  Open your assembly in SolidWorks.

components/common_software_integration.mdx

@@ -2,10 +2,4 @@ ROS has a large ecosystem of sensor drivers, some of which include pre-made URDF
 even simulation configurations. Refer to [Sensors supported by ROS](http://wiki.ros.org/Sensors).
 
 For the best experience, consider purchasing supported accessories from Clearpath Robotics for your
-robot, which will include simulation, visualization, and driver support. Refer to the following
-for more details:
-
-- [Computers](/docs/computers)
-- [Sensors](/docs/sensors)
-- [Manipulators](/docs/manipulators)
-- [Accessories](/docs/accessories)
+robot, which will include simulation, visualization, and driver support.

components/maintenance/getting_new_packages.mdx

@@ -1,6 +1,6 @@
 :::note
 
-If you are upgrading your robot from an older version of ROS, please refer to our upgrade instructions [here](https://clearpathrobotics.com/assets/guides/kinetic/kinetic-to-melodic/index.html) and [here](https://clearpathrobotics.com/assets/guides/melodic/melodic-to-noetic/index.html).
+If you are upgrading your robot from an older version of ROS, please refer to our upgrade instructions for upgrading to [Melodic](https://clearpathrobotics.com/assets/guides/kinetic/kinetic-to-melodic/index.html), [Noetic](https://clearpathrobotics.com/assets/guides/melodic/melodic-to-noetic/index.html) and [ROS 2 Humble](/docs/ros/installation/upgrading).
 
 :::
 

components/pacs_explanation_and_link.mdx

@@ -1,5 +1,5 @@
 :::note
 
-Refer to our [PACS page](/docs/tools/pacs) for more details about the configuration system, the available kits, and brackets that may help with your integration.
+Refer to our [PACS™ page](../pacs) for more details about the configuration system, the available kits, and brackets that may help with your integration.
 
 :::

components/pacs_mechanical.mdx

@@ -1,10 +1,10 @@
-[PACS](/docs/tools/pacs) is a Clearpath Robotics standard.
+[PACS™](../../../accessories/pacs) is a Clearpath Robotics standard.
 We add a grid of M5×0.8 holes onto the top plate of the robot.
 This grid of holes has a 80 mm X 80 mm spacing.
 You can create your own brackets to interface with these holes, or can use an existing Clearpath Robotics designed bracket.
 
 :::note
 
-Our [Sensors](/docs/sensors) and [Accessories](/docs/accessories) pages indicate the required bracket for the particular attachment.
+Our [Sensors](../../../accessories/sensors) and [Accessories](../../../accessories/add-ons) pages indicate the required bracket for the particular attachment.
 
 :::