Move static docs to openvox-docs, remove DITA

.github/workflows/tests.yaml

@@ -110,7 +110,7 @@ jobs:
       - name: Unit tests
         run: bundle exec rake tests:unit
 
-  run-dita:
+  generate-docs:
     runs-on: ubuntu-24.04
     steps:
     - name: Initialize
@@ -122,10 +122,8 @@ jobs:
         bundler-cache: true
     - name: Generate docs
       run: bundle exec rake docs:all
-    - name: Docs test
-      uses: dita-ot/dita-ot-action@4.3.5
-      with:
-        build: dita -i documentation/bolt.ditamap -o out -f html5 --processing-mode=strict
+    - name: Generate and verify Jekyll docs
+      run: bundle exec rake docs:jekyll docs:jekyll_verify
 
   local_transports:
     name: "local transport ${{ matrix.ruby }} ${{ matrix.os }}"
@@ -466,7 +464,7 @@ jobs:
       - cache_modules_linux
       - cache_modules_windows
       - unit
-      - run-dita
+      - generate-docs
       - local_transports
       - winrm_transport
       - apply

.gitignore

@@ -78,3 +78,4 @@ pwsh_module/PuppetBolt.psd1
 pwsh_module/autogenerated.tests.ps1
 pwsh_module/en-US
 pwsh_module/PuppetBolt
+/documentation/jekyll_build/

documentation/README.md

@@ -1,163 +1,41 @@
 # Bolt documentation
 
-This directory contains the markdown files used to generate the official
-[Bolt Documentation](https://puppet.com/docs/bolt/latest/bolt.html). To make
-changes to most of Bolt's documentation, you can edit the corresponding
-markdown file directly. However, some of Bolt's documentation is generated
-as part of the release process and requires edits to either Bolt's source
-code or to the template used to generate the documentation.
+This directory contains the ERB templates used to generate reference documentation
+for OpenBolt. Static documentation pages live in the
+[openvox-docs](https://github.com/OpenVoxProject/openvox-docs) repository.
 
-## Generated documentation
+## Generated reference documentation
 
-Several pages of Bolt's documentation are generated as part of Bolt's release
-process and do not have markdown files in this directory. Each of the generated
-pages has an associated Embedded Ruby template located in the
-[templates](./templates) directory as well as a [rake task](../rakelib/docs.rake)
-that is used to generate the documentation. Each rake task retrieves data from
-Bolt's source code and sends it to a rendering engine that generates a markdown
-file from the template. The generated markdown file is saved to the
-`documentation` directory.
+Several reference pages are generated from Bolt's source code. Each has an ERB
+template in the [templates](./templates) directory and a corresponding rake task in
+[rakelib/docs.rake](../rakelib/docs.rake).
 
-You can generate all documentation using the following rake task:
+Generate all reference pages:
 
 ```shell
-$ bundle exec rake docs:all
+bundle exec rake docs:all
 ```
 
-Here are each of the documenation pages that are generated, the files
-that you might need to modify to make changes to the generated documentation,
-and the rake task used to generate the documentation.
-
-### *nix shell commands
-
-**Documentation page** 
-- https://puppet.com/docs/bolt/latest/bolt_command_reference.html
-
-**Template file**
-- [`bolt_command_reference.md.erb`](./templates/bolt_command_reference.md.erb)
-
-**Relevant source code**
-- [`bolt_option_parser.rb`](../lib/bolt/bolt_option_parser.rb)
-
-To generate this documentation, run:
-
-```shell
-$ bundle exec rake docs:command_reference
-```
-
-### PowerShell cmdlets
-
-**Documentation page** 
-- https://puppet.com/docs/bolt/latest/bolt_cmdlet_reference.html
-
-**Template file**
-- [`bolt_cmdlet_reference.md.erb`](./templates/bolt_cmdlet_reference.md.erb)
-
-**Relevant source code**
-- [`bolt_option_parser.rb`](../lib/bolt/bolt_option_parser.rb)
-- [`pwsh.rb`](../rakelib/lib/pwsh.rb)
-
-To generate this documentation, run:
-
-```shell
-$ bundle exec rake docs:cmdlet_reference
-```
-
-### Bolt functions
-
-**Documentation page**
-- https://puppet.com/docs/bolt/latest/plan_functions.html
-
-**Template file**
-- [`reference.md.erb`](./templates/reference.md.erb)
-
-**Relevant source code**
-
-The rake task for this page uses `puppet-strings` to generate documentation
-from comments in a function's source code. Bolt ships with several core modules
-that are located in the `bolt-modules` directory. To modify the documentation
-for a plan function, locate its file and modify the comments.
-
-- [`boltlib`](../bolt-modules/boltlib/lib/puppet/functions)
-- [`ctrl`](../bolt-modules/boltlib/lib/puppet/functions)
-- [`file`](../bolt-modules/boltlib/lib/puppet/functions)
-- [`out`](../bolt-modules/boltlib/lib/puppet/functions)
-- [`prompt`](../bolt-modules/boltlib/lib/puppet/functions)
-- [`system`](../bolt-modules/boltlib/lib/puppet/functions)
-
-To generate this documentation, run:
-
-```shell
-$ bundle exec rake docs:function_reference
-```
-
-### `bolt-defaults.yaml` options
-
-**Documentation page**
-- https://puppet.com/docs/bolt/latest/bolt_defaults_reference.html
-
-**Template file**
-- [`bolt_defaults_reference.md.erb`](./templates/bolt_defaults_reference.md.erb)
-
-**Relevant source code**
-- [`config/options.rb`](../lib/bolt/config/options.rb)
-
-To generate this documentation, run:
-
-```shell
-$ bundle exec rake docs:defaults_reference
-```
-
-### `bolt-project.yaml` options
-
-**Documentation page**
-- https://puppet.com/docs/bolt/latest/bolt_project_reference.html
-
-**Template file**
-- [`bolt_project_reference.md.erb`](./templates/bolt_project_reference.md.erb)
-
-**Relevant source code**
-- [`config/options.rb`](../lib/bolt/config/options.rb)
-
-To generate this documentation, run:
+Generate Jekyll-ready output (rendered templates + `.md` links rewritten to `.html`):
 
 ```shell
-$ bundle exec rake docs:project_reference
+bundle exec rake docs:jekyll
 ```
 
-### Transport configuration options
+Output is written to `documentation/jekyll_build/` (gitignored). The openvox-docs
+copy pipeline runs `rake docs:jekyll` and copies this directory to pick up the
+reference pages.
 
-**Documentation page**
-- https://puppet.com/docs/bolt/latest/bolt_transports_reference.html
+## Reference pages and their templates
 
-**Template file**
-- [`bolt_transports_reference.md.erb`](./templates/bolt_transports_reference.md.erb)
-
-**Relevant source code**
-- [`config/transport/`](../lib/bolt/config/transport) (Each transport defines
-  its available options.)
-- [`config/transport/options.rb`](../lib/bolt/config/transport/options.rb)
-
-To generate this documentation, run:
-
-```shell
-$ bundle exec rake docs:transports_reference
-```
-
-### Escalating privilege with Bolt
-
-**Documentation page**
-- https://puppet.com/docs/bolt/latest/privilege_escalation.html
-
-**Template file**
-- [`privilege_escalation.md.erb`](./templates/privilege_escalation.md.erb)
-
-**Relevant source code**
-- [`bolt_option_parser.rb`](../lib/bolt/bolt_option_parser.rb)
-- [`config/transport/options.rb`](../lib/bolt/config/transport/options.rb)
-
-To generate this documentation, run:
-
-```shell
-$ bundle exec rake docs:privilege_escalation
-```
+| Page | Template | Rake task |
+| ---- | -------- | --------- |
+| Shell command reference | `templates/bolt_command_reference.md.erb` | `docs:command_reference` |
+| PowerShell cmdlet reference | `templates/bolt_cmdlet_reference.md.erb` | `docs:cmdlet_reference` |
+| Plan functions | `templates/plan_functions.md.erb` | `docs:function_reference` |
+| `bolt-defaults.yaml` options | `templates/bolt_defaults_reference.md.erb` | `docs:defaults_reference` |
+| `bolt-project.yaml` options | `templates/bolt_project_reference.md.erb` | `docs:project_reference` |
+| Transport configuration | `templates/bolt_transports_reference.md.erb` | `docs:transports_reference` |
+| Privilege escalation | `templates/privilege_escalation.md.erb` | `docs:privilege_escalation` |
+| Bolt data types | `templates/bolt_types_reference.md.erb` | `docs:type_reference` |
+| Packaged modules | `templates/packaged_modules.md.erb` | `docs:packaged_modules` |