rename process-docs to examples/simple (#17)

Author: AlexanderLanin

.vscode/settings.json

@@ -0,0 +1,36 @@
+{
+  // General Settings
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "files.trimTrailingWhitespace": true,
+  "editor.insertSpaces": true,
+  "editor.tabCompletion": "on",
+
+  // When using ruff for formatting 88 characters per line is the standard.
+  "editor.rulers": [88],
+  "[python]": {
+    // Opinionated option for the future:
+    // "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.sortImports": "explicit"
+    },
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  },
+
+  // RST Settings
+  "[restructuredtext]": {
+    "editor.tabSize": 3
+  },
+  //
+  //
+  "python.testing.pytestArgs": [
+    ".",
+    "--ignore-glob=bazel-*/*",
+    "--ignore-glob=.venv_docs/*",
+    "--ignore-glob=_build/*"
+  ],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true,
+  "bazel.lsp.command": "bazel",
+  "bazel.lsp.args": ["run", "//:starpls_server"]
+}

BUILD

@@ -16,7 +16,7 @@ load("@score_cr_checker//:cr_checker.bzl", "copyright_checker")
 copyright_checker(
     name = "copyright",
     srcs = [
-        "process-docs",
+        "examples",
         "src",
         "//:BUILD",
         "//:MODULE.bazel",

README.md

@@ -29,7 +29,7 @@ bazel_dep(name = "score_docs_as_code", version = "0.1.0")
 And make sure to also add the S-core bazel registry to your `.bazelrc` file
 
 ```starlark
-common --registry=https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/  
+common --registry=https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/
 common --registry=https://bcr.bazel.build
 ```
 
@@ -61,7 +61,7 @@ docs(
 #### 2. Adapt your conf.py if needed
 
 ```python
-# ... 
+# ...
 extensions = [
     "sphinx_design",
     "sphinx_needs",
@@ -76,7 +76,7 @@ extensions = [
 ```
 
 Make sure that your conf.py imports all of the extensions you want to enable.\
-For a full example look at [This repos conf.py](process-docs/conf.py)
+For a full example look at [a simple example](examples/simple)
 
 #### 3. Run a documentation build:
 

process-docs/BUILD examples/simple/BUILDprocess-docs/BUILD renamed to examples/simple/BUILD

@@ -21,13 +21,13 @@ load("//:docs.bzl", "docs")
 # - `docs:docs` for building documentation at build-time
 
 docs(
-    conf_dir = "process-docs",
+    conf_dir = "examples/simple",
     docs_targets = [
         {
             "suffix": "",  # local without external needs
         },
     ],
-    source_dir = "process-docs",
+    source_dir = "examples/simple",
     source_files_to_scan_for_needs_links = [
         # Note: you can add filegroups, globs, or entire targets here.
         "//src:score_extension_files",

process-docs/conf.py examples/simple/conf.pyprocess-docs/conf.py renamed to examples/simple/conf.py

@@ -16,22 +16,17 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-import logging
-
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "score_docs_as_code"
-author = "Score"
+project = "Simple Example Project"
+author = "S-CORE"
 version = "0.1"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-logger = logging.getLogger("process-docs")
-logger.debug("Loading score_docs_as_code conf.py")
-
 
 extensions = [
     "sphinx_design",
@@ -44,13 +39,11 @@
     "score_layout",
 ]
 
-logger.debug("After loading extensions")
-
 exclude_patterns = [
-    # The following entries are not required when building the documentation
-    # via 'bazel build //docs:docs', as that command runs in a sandboxed environment.
-    # However, when building the documentation via 'sphinx-build' or esbonio,
-    # these entries are required to prevent the build from failing.
+    # The following entries are not required when building the documentation via 'bazel
+    # build //docs:docs', as that command runs in a sandboxed environment. However, when
+    # building the documentation via 'bazel run //docs:incremental' or esbonio, these
+    # entries are required to prevent the build from failing.
     "bazel-*",
     ".venv_docs",
 ]
@@ -59,6 +52,3 @@
 
 # Enable numref
 numfig = True
-
-
-logger.debug("After loading S-CORE conf.py")

process-docs/index.rst examples/simple/index.rstprocess-docs/index.rst renamed to examples/simple/index.rst

@@ -1,7 +1,7 @@
 # This file is at the root level, as it applies to all Python code,
 # not only to docs or to tools.
-[tool.pyright] 
-extends = "bazel-bin/process-docs/ide_support.runfiles/score_python_basics~/pyproject.toml"
+[tool.pyright]
+extends = "bazel-bin/examples/simple/ide_support.runfiles/score_python_basics~/pyproject.toml"
 
 exclude = [
     "**/__pycache__",
@@ -11,7 +11,7 @@ exclude = [
 ]
 
 [tool.ruff]
-extend = "bazel-bin/process-docs/ide_support.runfiles/score_python_basics~/pyproject.toml"
+extend = "bazel-bin/examples/simple/ide_support.runfiles/score_python_basics~/pyproject.toml"
 
 extend-exclude = [
     "**/__pycache__",

pyproject.toml

@@ -11,7 +11,7 @@ It should be treated as a 'get-started' guide, giving you all needed information
     1. Install Bazelisk (version manager for Bazel)
     2. Create the Python virtual environment:
    ```bash
-   bazel run //process-docs:ide_support
+   bazel run //your-docs-dir:ide_support
    ```
     3. Select `.venv_docs/bin/python` as the python interpreter inside your IDE
     *Note: This virtual environment does **not** have pip, therefore `pip install` is not available.*
@@ -57,7 +57,7 @@ It should be treated as a 'get-started' guide, giving you all needed information
 ## score_docs_as_code Directory Architecture
 
 ```
-process-docs/         # Local documentation to test functionality
+examples/             # Shows how to use doc-as-code tooling
 src/
 ├── assets/           # Documentation styling (CSS)
 ├── decision_records/ # Architecture Decision Records (ADRs)