chore: use docs-dev instead of docs dir for docs (#4522)

* chore: use `docs-dev` instead of `docs` folder

* patch version bump

* Rollback an incorrect rename

* Use exact docs dir in the helper comment

* Revert some overeager renamings

* Moving `docs` to `docs-dev`

* Update Docs Paths

---------

Co-authored-by: eric-forte-elastic <[email protected]>

Author: traut

.github/workflows/attack-coverage-update.yml

@@ -3,7 +3,7 @@ on:
   workflow_dispatch:
       inputs:
         update-coverage:
-          description: 'Update the docs/ATT&CK-coverage.md file'
+          description: 'Update the docs-dev/ATT&CK-coverage.md file'
           required: true
           default: '--update-coverage'
 
@@ -37,25 +37,25 @@ jobs:
           git config --global user.email "[email protected]"
           git config --global user.name "protectionsmachine"
 
-      - name: Update navigator gist files and docs/ATT&CK-coverage.md file.
+      - name: Update navigator gist files and docs-dev/ATT&CK-coverage.md file.
         env:
           GITHUB_TOKEN: "${{ secrets.WRITE_TRADEBOT_GIST_TOKEN }}"
         run: |
          python -m detection_rules dev update-navigator-gists "${{ github.event.inputs.update-coverage }}"
-         git add docs/"ATT\&CK-coverage.md"
+         git add docs-dev/"ATT\&CK-coverage.md"
 
       - name: Create Pull Request
         uses: peter-evans/[email protected]
         with:
           assignees: '${{github.actor}}'
           delete-branch: true
           branch: "update-attack-coverage"
-          commit-message: "Update ATT&CK coverage URL(s) in docs/ATT&CK-coverage.md"
+          commit-message: "Update ATT&CK coverage URL(s) in docs-dev/ATT&CK-coverage.md"
           branch-suffix: "short-commit-hash"
           base: main
-          title: 'Update ATT&CK coverage URL(s) in docs/ATT&CK-coverage.md'
+          title: 'Update ATT&CK coverage URL(s) in docs-dev/ATT&CK-coverage.md'
           body: |
-            Update ATT&CK coverage URL(s) in docs/ATT&CK-coverage.md
+            Update ATT&CK coverage URL(s) in docs-dev/ATT&CK-coverage.md
 
             - Autogenerated from job `attack-coverage-update: pr`.
           labels: "backport: auto"

.github/workflows/version-code-and-release.yml

@@ -8,7 +8,7 @@ on:
       - 'hunting/**/*.py'
       - 'pyproject.toml'
       - 'Makefile'
-      - 'docs/**'
+      - 'docs-dev/**'
       - 'detection_rules/**'
       - 'tests/**'
       - '!hunting/**/*.md'

.gitignore

@@ -77,7 +77,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs-dev/_build/
 
 # PyBuilder
 target/

CLI.md

@@ -498,7 +498,7 @@ python -m detection_rules kibana import-rules -d test-export-rules -o
 
 ### Exporting rules
 
-This command should be run with the `CUSTOM_RULES_DIR` envvar set, that way proper validation is applied to versioning when the rules are downloaded. See the [custom rules docs](docs/custom-rules.md) for more information.
+This command should be run with the `CUSTOM_RULES_DIR` envvar set, that way proper validation is applied to versioning when the rules are downloaded. See the [custom rules docs](docs-dev/custom-rules.md) for more information.
 
 ```
 python -m detection_rules kibana export-rules -h

detection_rules/custom_rules.py

@@ -11,11 +11,12 @@
 
 from .main import root
 from .utils import get_etc_path, load_etc_dump, ROOT_DIR
+from .docs import REPO_DOCS_DIR
 
 from semver import Version
 
 DEFAULT_CONFIG_PATH = Path(get_etc_path('_config.yaml'))
-CUSTOM_RULES_DOC_PATH = Path(ROOT_DIR).joinpath('docs', 'custom-rules.md')
+CUSTOM_RULES_DOC_PATH = Path(ROOT_DIR).joinpath(REPO_DOCS_DIR, 'custom-rules.md')
 
 
 @root.group('custom-rules')

detection_rules/devtools.py

@@ -34,7 +34,7 @@
                     refresh_main_schema)
 from .cli_utils import single_collection
 from .config import parse_rules_config
-from .docs import IntegrationSecurityDocs, IntegrationSecurityDocsMDX
+from .docs import IntegrationSecurityDocs, IntegrationSecurityDocsMDX, REPO_DOCS_DIR
 from .ecs import download_endpoint_schemas, download_schemas
 from .endgame import EndgameSchemaManager
 from .eswrap import CollectEvents, add_range_to_dsl
@@ -802,7 +802,7 @@ def deprecate_rule(ctx: click.Context, rule_file: Path, deprecation_folder: Path
               help='GitHub token to push to gist', hide_input=True)
 @click.option('--gist-id', default=NAVIGATOR_GIST_ID, help='Gist ID to be updated (must exist).')
 @click.option('--print-markdown', is_flag=True, help='Print the generated urls')
-@click.option('--update-coverage', is_flag=True, help='Update the docs/ATT&CK-coverage.md file')
+@click.option('--update-coverage', is_flag=True, help=f'Update the {REPO_DOCS_DIR}/ATT&CK-coverage.md file')
 def update_navigator_gists(directory: Path, token: str, gist_id: str, print_markdown: bool,
                            update_coverage: bool) -> list:
     """Update the gists with new navigator files."""
@@ -857,7 +857,7 @@ def raw_permalink(raw_link):
         click.echo('\n'.join(markdown) + '\n')
 
     if update_coverage:
-        coverage_file_path = get_path('docs', 'ATT&CK-coverage.md')
+        coverage_file_path = get_path(REPO_DOCS_DIR, 'ATT&CK-coverage.md')
         header_lines = textwrap.dedent("""# Rule coverage
 
 ATT&CK navigator layer files are generated when a package is built with `make release` or

detection_rules/docs.py

@@ -24,6 +24,8 @@
 from .rule_loader import DeprecatedCollection, RuleCollection
 from .utils import load_etc_dump, save_etc_dump
 
+REPO_DOCS_DIR = "docs-dev"
+
 
 class PackageDocument(xlsxwriter.Workbook):
     """Excel document for summarizing a rules package."""