Skip to content

Commit 78d599b

Browse files
MaximilianSoerenPollakMaximilianSoerenPollak
authored
add README (#6)
1 parent 29c622c commit 78d599b

2 files changed

Lines changed: 164 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 162 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,162 @@
1-
# docs-as-code
2-
Contains docs-as-code tooling
1+
# Bazel Sphinx Documentation Builder
2+
3+
A Bazel module providing comprehensive tools and extensions for building Sphinx documentation within Bazel projects.
4+
5+
## Overview
6+
7+
This module allows you to easily integrate Sphinx documentation generation into your Bazel build system. It provides a collection of utilities, extensions, and themes specifically designed to enhance documentation capabilities while maintaining Bazel's reproducible build environment.
8+
9+
## Features
10+
11+
- Seamless integration with Bazel build system
12+
- Custom Sphinx extensions for enhanced documentation
13+
- Support for PlantUML diagrams
14+
- Source code linking capabilities
15+
- Metamodel validation and checks
16+
- Custom layouts and themes
17+
- Header service for consistent documentation styling
18+
19+
## Getting Started
20+
21+
### Installation
22+
23+
Add the module to your `MODULE.bazel` file:
24+
25+
```starlark
26+
bazel_dep(name = "docs-as-code", version = "0.1.0")
27+
```
28+
29+
And make sure to also add the S-core bazel registry to your `.bazelrc` file
30+
31+
```starlark
32+
common --registry=https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/
33+
common --registry=https://bcr.bazel.build
34+
```
35+
36+
______________________________________________________________________
37+
38+
### Basic Usage
39+
40+
#### 1. Import the `docs()` macro in your BUILD file:
41+
42+
```python
43+
load("@docs-as-code//docs.bzl", "docs")
44+
45+
docs(
46+
conf_dir = "<your sphinc conf dir>",
47+
source_dir = "<your sphinx source dir>",
48+
docs_targets = [
49+
{
50+
# For more detailed explenation look at the 'docs_targets' section
51+
"suffix": "", # This creates the normal 'incremental' and 'docs' target
52+
},
53+
],
54+
source_files_to_scan_for_needs_links = [
55+
# Note: you can add filegroups, globs, or entire targets here.
56+
"<your targets that the source code linker should scan>"
57+
],
58+
)
59+
```
60+
61+
#### 2. Adapt your conf.py if needed
62+
63+
```python
64+
# ...
65+
extensions = [
66+
"sphinx_design",
67+
"sphinx_needs",
68+
"sphinxcontrib.plantuml",
69+
"score_plantuml",
70+
"score_metamodel",
71+
"score_draw_uml_funcs",
72+
"score_source_code_linker",
73+
"score_layout",
74+
]
75+
# ...
76+
```
77+
78+
Make sure that your conf.py imports all of the extensions you want to enable.\
79+
For a full example look at [This repos conf.py](process-docs/conf.py)
80+
81+
#### 3. Run a documentation build:
82+
83+
```bash
84+
bazel run //path/to/BUILD-file:incremental # documentation at '_build/'
85+
bazel build //path/to/BUILD-file:docs # documentation at 'bazel-bin/
86+
```
87+
88+
#### 4. Access your documentation at
89+
90+
- `_build/` for incremental
91+
- `bazel-bin/bazel-bin/<BUILD FILE FOLDER NAME>/docs/_build/html`
92+
93+
______________________________________________________________________
94+
95+
### Available Targets
96+
97+
Using the `docs` macro enables multiple targets which are now useable.
98+
99+
| Target Name | What it does | How to execute |
100+
|---------------|-----------------------------------------------------------|-----------------|
101+
| docs | Builds documentation in sandbox | `bazel build` |
102+
| incremental | Builds documentation incrementally (faster) | `bazel run` |
103+
| live_preview | Creates a live_preview of the documentation viewable in a local server | `bazel run` |
104+
| ide_support | Creates virtual environment under '.venv_docs' | `bazel run` |
105+
106+
______________________________________________________________________
107+
108+
## Configuration Options
109+
110+
The `docs()` macro accepts the following arguments:
111+
112+
| Parameter | Description | Required | Default |
113+
|-----------|-------------|----------|---------|
114+
| `conf_dir` | Path to the 'conf.py' containing folder | No | 'docs' |
115+
| `source_dir` | Documentation source files (RST, MD) | No | 'docs' |
116+
| `build_dir_for_incremental` | Output folder for the incremental build | No | '\_build' |
117+
| `docs_targets` | List of dictionaries which allows multi-repo setup | Yes | - |
118+
| `source_files_to_scan_for_needs_links` | List of targets,globs,filegroups that the 'source_code_linker' should parse | No | `[]` |
119+
| `visibility` | Bazel visibility | No | `None` |
120+
121+
## Advanced Usage
122+
123+
### Custom Configuration
124+
125+
#### Docs-targets
126+
127+
!! TODO !!
128+
This should be filled out after the local mutli-repo tests are integrated and we have examples of different configurations
129+
130+
## Available Extensions
131+
132+
This module includes several custom Sphinx extensions to enhance your documentation:
133+
134+
### Score Layout Extension
135+
136+
Custom layout options for Sphinx HTML output.
137+
[Learn more](src/extensions/score_layout/README.md)
138+
139+
### Score Header Service
140+
141+
Consistent header styling across documentation pages.
142+
[Learn more](src/extensions/score_header_service/README.md)
143+
144+
### Score Metamodel
145+
146+
Validation and checking of documentation structure against a defined metamodel.
147+
[Learn more](src/extensions/score_metamodel/README.md)
148+
149+
### Score Source Code Linker
150+
151+
Links between requirements documentation and source code implementations.
152+
[Learn more](src/extensions/score_source_code_linker/README.md)
153+
154+
### Score PlantUML
155+
156+
Integration with PlantUML for generating diagrams.
157+
[Learn more](src/extensions/README.md)
158+
159+
### Score Draw UML Functions
160+
161+
Helper functions for creating UML diagrams.
162+
[Learn more](src/extensions/score_draw_uml_funcs/README.md)

‎src/extensions/score_layout/__init__.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@
1414

1515
from sphinx.application import Sphinx
1616

17-
from score_layout import html_options, sphinx_options
17+
import html_options
18+
import sphinx_options
1819

1920

2021
def setup(app: Sphinx) -> dict[str, str | bool]:

0 commit comments

Comments
 (0)