Skip to content

Commit 224445c

Browse files
theletterftheletterf
authored
Merge branch 'main' into crosslinks-in-toc-take-three
2 parents 3182442 + 85607e1 commit 224445c

File tree

33 files changed

+725
-974
lines changed

33 files changed

+725
-974
lines changed

‎.github/workflows/deploy-api-lambda-edge.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
name: "Deploy API Lambda (edge)"
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
deploy:
13+
uses: ./.github/workflows/deploy-api-lambda.yml
14+
with:
15+
environment: edge

‎.github/workflows/deploy-api-lambda-prod.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: "Deploy API Lambda (prod)"
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
ref:
7+
description: 'The git tag of the release to deploy, e.g. 3.0.0'
8+
required: true
9+
type: string
10+
11+
permissions:
12+
contents: read
13+
14+
jobs:
15+
deploy:
16+
uses: ./.github/workflows/deploy-api-lambda.yml
17+
with:
18+
environment: prod
19+
ref: refs/tags/${{ github.event.inputs.ref }}

‎.github/workflows/deploy-api-lambda-staging.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: "Deploy API Lambda (staging)"
2+
3+
on:
4+
release:
5+
types:
6+
- published
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
deploy:
13+
uses: ./.github/workflows/deploy-api-lambda.yml
14+
with:
15+
environment: staging
16+
ref: refs/tags/${{ github.event.release.tag_name }}

‎.github/workflows/deploy-api-lambda.yml‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,16 @@
11
name: Deploy API Lambda
2+
23
on:
3-
push:
4-
branches:
5-
- main
6-
workflow_dispatch:
4+
workflow_call:
5+
inputs:
6+
environment:
7+
required: true
8+
type: string
9+
description: edge, staging or prod
10+
ref:
11+
required: false
12+
type: string
13+
default: ${{ github.ref }}
714

815
permissions:
916
contents: read
@@ -13,22 +20,21 @@ jobs:
1320
permissions:
1421
contents: read
1522
uses: ./.github/workflows/build-api-lambda.yml
16-
23+
with:
24+
ref: ${{ inputs.ref }}
25+
1726
deploy:
27+
concurrency: ${{ github.workflow }}-${{ inputs.environment }}
1828
permissions:
1929
contents: read
2030
id-token: write
2131
runs-on: ubuntu-latest
2232
needs: build
23-
environment: docs-api-edge
33+
environment: docs-api-${{ inputs.environment }}
2434
env:
2535
ZIP_FILE: api-lambda.zip
2636
steps:
2737
- uses: actions/checkout@v5
28-
- name: Download bootstrap binary
29-
uses: actions/download-artifact@v4
30-
with:
31-
name: api-lambda-binary
3238

3339
- name: Download bootstrap binary
3440
uses: actions/download-artifact@v4
@@ -41,11 +47,13 @@ jobs:
4147
4248
- uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4.3.1
4349
with:
44-
role-to-assume: arn:aws:iam::197730964718:role/elastic-docs-v3-api-deployer-edge
50+
role-to-assume: arn:aws:iam::197730964718:role/elastic-docs-v3-api-deployer-${{ inputs.environment }}
4551
aws-region: us-east-1
4652

4753
- name: Upload Lambda function
4854
run: |
4955
aws lambda update-function-code \
50-
--function-name elastic-docs-v3-edge-api \
56+
--function-name "elastic-docs-v3-${ENVIRONMENT}-api" \
5157
--zip-file "fileb://${ZIP_FILE}"
58+
env:
59+
ENVIRONMENT: ${{ inputs.environment }}

‎.github/workflows/preview-build.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -448,7 +448,7 @@ jobs:
448448
comment:
449449
if: >
450450
startsWith(github.event_name, 'pull_request')
451-
&& inputs.disable-comments != 'true'
451+
&& inputs.disable-comments != true
452452
&& needs.build.outputs.deployment_result
453453
&& needs.check.outputs.any_modified
454454
runs-on: ubuntu-latest
@@ -537,7 +537,7 @@ jobs:
537537
});
538538
}
539539
- name: Comment on docs changes about versioning requirements
540-
if: inputs.enable-cumulative-comment == 'true'
540+
if: inputs.enable-cumulative-comment == true
541541
uses: actions/github-script@v7
542542
with:
543543
github-token: ${{ secrets.GITHUB_TOKEN }}

‎AGENTS.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# AI Assistant Guide for docs-builder
2+
3+
This file contains instructions and guidance for AIs when working with the docs-builder repository.
4+
5+
## Repository overview
6+
7+
This is Elastic's distributed documentation tooling system built on .NET 9, consisting of:
8+
9+
- **docs-builder**: CLI tool for building single documentation sets
10+
- **docs-assembler**: CLI tool for assembling multiple doc sets
11+
- Written in C# and F# with extensive Markdown processing capabilities
12+
13+
## Essential commands
14+
15+
### Development
16+
```bash
17+
# Ensure no compilation failures -- run this to confirm the absence of build errors.
18+
dotnet build
19+
20+
# Run docs-builder locally
21+
dotnet run --project src/tooling/docs-builder
22+
23+
# Run all the unit tests which complete fast.
24+
./build.sh unit-test
25+
26+
# Clean all the build artifacts located in .artifacts folder
27+
./build.sh clean
28+
29+
# Produce native binaries -- only call this if a change touches serialization and you are committing on behalf of the developer.
30+
./build.sh publishbinaries
31+
32+
```
33+
34+
### Linting and Code Quality
35+
36+
```bash
37+
# Format code. Always run this when output contains formatting errors.
38+
dotnet format
39+
40+
# Run specific test project
41+
dotnet test tests/Elastic.Markdown.Tests/
42+
43+
# Run tests with verbose output
44+
dotnet test --logger "console;verbosity=detailed"
45+
```
46+
47+
## Key architecture Points
48+
49+
### Main Projects
50+
51+
- `src/Elastic.Markdown/` - Core Markdown processing engine
52+
- `src/tooling/docs-builder/` - Main CLI application
53+
- `src/tooling/docs-assembler/` - Assembly tool
54+
- `src/Elastic.Documentation.Site/` - Web rendering components
55+
56+
### Testing Structure
57+
58+
- `tests/` - C# unit tests
59+
- `tests/authoring/` - F# authoring tests
60+
- `tests-integration/` - Integration tests
61+
62+
### Configuration
63+
64+
- `config/` - YAML configuration files
65+
- `Directory.Build.props` - MSBuild properties
66+
- `Directory.Packages.props` - Centralized package management
67+
68+
## Development guidelines
69+
70+
### Adding New Features
71+
72+
1. **Markdown Extensions**: Add to `src/Elastic.Markdown/Myst/`
73+
2. **CLI Commands**: Extend `src/tooling/docs-builder/Cli/` or `docs-assembler/Cli/`
74+
3. **Web Components**: Add to `src/Elastic.Documentation.Site/`
75+
4. **Configuration**: Modify `src/Elastic.Documentation.Configuration/`
76+
77+
### Code style
78+
79+
- Follow existing C# and F# conventions in the codebase
80+
- ...
81+
82+
### Testing requirements
83+
84+
- Add unit tests for new functionality
85+
- Use F# for authoring/documentation-specific tests
86+
- ...
87+
88+
### Common patterns
89+
90+
- ...
91+
92+
## Documentation
93+
94+
The repository is self-documenting:
95+
96+
- `/docs/` contains comprehensive documentation
97+
98+
You MUST update the documentation when there are changes in the markdown syntax or rendering behaviour.
99+
100+
## Useful file locations
101+
102+
- Entry points: `src/tooling/docs-builder/Program.cs`, `src/tooling/docs-assembler/Program.cs`
103+
- Markdown processing: `src/Elastic.Markdown/Myst/`
104+
- Web assets: `src/Elastic.Documentation.Site/Assets/`
105+
- Configuration schemas: `src/Elastic.Documentation.Configuration/`
106+
- Test helpers: `tests/Elastic.Markdown.Tests/TestHelpers.cs`

‎config/assembler.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ environments:
1717
auth: nPocPUG0wiH68jsVeyRSxA
1818
preview: env-507
1919
cookies_win: x
20+
feature_flags:
21+
SEARCH_OR_ASK_AI: true
2022
edge:
2123
uri: https://d34ipnu52o64md.cloudfront.net
2224
path_prefix: docs

‎config/legacy-url-mappings.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ stack: &stack [ '9.0+', '8.19', '8.18', '8.17', '8.16', '8.15', '8.14', '8.13',
88

99
mappings:
1010
en/apm/agent/android/: [ '1.2.0' , '0.x' ]
11-
en/apm/agent/dotnet/: [ '1.33.0' ]
11+
en/apm/agent/dotnet/: [ '1.34.0' ]
1212
en/apm/agent/go/: [ '2.7.1', '1.x', '0.5' ]
1313
en/apm/agent/java/: ['1.54.0', '0.7', '0.6']
1414
en/apm/agent/nodejs/: [ '4.x', '3.x', '2.x', '1.x' ]

‎docs/_snippets/applies_to-key.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
`applies_to` accepts the following keys in this structure:
1+
`applies_to` accepts the following keys in this structure.
22

33
* `serverless`: Applies to [Elastic Cloud Serverless](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/serverless).
44
* `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started/create-security-project).
@@ -10,7 +10,7 @@
1010
* `eck`: Applies to [Elastic Cloud on Kubernetes](https://www.elastic.co/docs/deploy-manage/deploy/cloud-on-k8s) deployments.
1111
* `self`: Applies to [self-managed](https://www.elastic.co/docs/deploy-manage/deploy/self-managed) deployments.
1212
* `ess`: Applies to [Elastic Cloud Hosted](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/cloud-hosted) deployments.
13-
* `product`: Applies to a specific product that uses a unique versioning scheme (e.g. not `stack`, `ece`, `eck`).
13+
* `product`: Applies to a specific product that uses a unique versioning scheme (for example, not `stack`, `ece`, `eck`).
1414
* `apm_agent_dotnet`: Applies to the [Elastic APM .NET agent](https://www.elastic.co/docs/reference/apm/agents/dotnet).
1515
* `apm_agent_go`: Applies to the [Elastic APM Go agent](https://www.elastic.co/docs/reference/apm/agents/go).
1616
* `apm_agent_java`: Applies to the [Elastic APM Java agent](https://www.elastic.co/docs/reference/apm/agents/java).
@@ -30,7 +30,7 @@
3030
* `edot_node`: Applies to the [Elastic Distribution of OpenTelemetry Node.js](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/nodejs/) (EDOT Node.js).
3131
* `edot_php`: Applies to the [Elastic Distribution of OpenTelemetry PHP](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/php/) (EDOT PHP).
3232
* `edot_python`: Applies to the [Elastic Distribution of OpenTelemetry Python](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/python/) (EDOT Python).
33-
33+
3434
:::{note}
35-
The `products` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](/syntax/frontmatter.md#products) is used to drive elastic.co search filters.
35+
The `product` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](/syntax/frontmatter.md#products) is used to drive elastic.co search filters.
3636
:::

‎docs/_snippets/applies_to-version.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
* `Major.Minor`
44
* `Major.Minor.Patch`
55

6+
Regardless of the version format used in the source file, the version number is always rendered in the `Major.Minor.Patch` format.
7+
68
:::{note}
7-
Regardless of the version format used in the source file,
8-
the version number will always be rendered in the `Major.Minor.Patch` format.
9-
:::
9+
**Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6` will be displayed as `stack: ga 9.1.2, ga 9.0.6, ga 8.19.2, ga 8.18.6`. Items without versions (like `ga` without a version or `all`) are sorted last.
10+
:::

0 commit comments

Comments
 (0)