Skip to content

Commit 7cc289e

Browse files
bmorelli25bmorelli25
authored
Add to Migration, Syntax, and Contribution Guides (#170)
### Summary * Adds to migration, syntax, and contribution guides * Adds issue templates for bugs and enhancements * Adds scripts helpful for migration tasks
1 parent 80e512e commit 7cc289e

File tree

23 files changed

+676
-170
lines changed

23 files changed

+676
-170
lines changed

‎.github/ISSUE_TEMPLATE/bug-report.yaml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: "Bug Report"
2+
description: "File a bug report."
3+
labels: ["bug"]
4+
projects: ["elastic/1625"]
5+
body:
6+
- type: "textarea"
7+
id: description
8+
attributes:
9+
label: "Describe the bug"
10+
description: "A clear and concise description of what the bug is. If applicable, add screenshots to help explain your problem."
11+
validations:
12+
required: true
13+
- type: "textarea"
14+
id: expected
15+
attributes:
16+
label: "Expected behavior"
17+
description: "A clear and concise description of what you expected to happen."
18+
validations:
19+
required: true
20+
- type: "textarea"
21+
id: repro
22+
attributes:
23+
label: "Steps to reproduce"
24+
description: "If relevant, provide steps to reproduce the issue."
25+
validations:
26+
required: false
27+
- type: "checkboxes"
28+
id: tooling
29+
attributes:
30+
label: "Tooling"
31+
description: "Select the tool this bug relates to."
32+
options:
33+
- label: "docs-builder"
34+
required: false
35+
- label: "migration tooling"
36+
required: false
37+
- label: "I'm not sure"
38+
required: false

‎.github/ISSUE_TEMPLATE/enhancement.yaml‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
name: Feature Request
2+
description: Suggest an idea for improving docs-builder.
3+
title: "[Feature Request]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for taking the time to suggest an improvement to docs-builder! Please fill out this form as completely as possible.
10+
11+
- type: checkboxes
12+
attributes:
13+
label: Prerequisites
14+
description: Please verify you have completed the following
15+
options:
16+
- label: I have searched existing issues to ensure this feature hasn't already been requested
17+
required: true
18+
- label: I have tested using the latest version of docs-builder
19+
required: true
20+
21+
- type: textarea
22+
id: problem
23+
attributes:
24+
label: What problem are you trying to solve?
25+
description: |
26+
Describe the context and limitation you're encountering. Remember that it might not be obvious to others why this is important!
27+
placeholder: |
28+
Example: When building documentation for my project, I often need to update the revision date at the top of each file. Currently, I have to manually edit each file, which is time-consuming and error-prone.
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: solution
34+
attributes:
35+
label: Proposed Solution
36+
description: |
37+
Describe your proposed solution. Include as much detail as you can, but remember that there might be other solutions we haven't thought of!
38+
placeholder: |
39+
Example: Add a CLI flag --auto-update-revision-date that automatically updates a specified metadata field in all documentation files when building.
40+
validations:
41+
required: true
42+
43+
- type: textarea
44+
id: examples
45+
attributes:
46+
label: Examples and Research
47+
description: |
48+
Please provide any relevant examples, research, or references that support this feature request:
49+
- Similar features in other documentation tools
50+
- Code samples showing how you'd use this feature
51+
- Links to relevant standards or conventions
52+
- Screenshots or diagrams of your proposed solution
53+
placeholder: |
54+
- MkDocs has a similar feature using their `git-revision-date-localized` plugin
55+
- Jekyll's `last_modified_at` plugin demonstrates this functionality
56+
validations:
57+
required: false
58+
59+
- type: textarea
60+
id: alternatives
61+
attributes:
62+
label: Alternative Solutions
63+
description: |
64+
What alternative solutions have you considered or tried? Why aren't they sufficient?
65+
placeholder: |
66+
I've tried using git hooks to update the dates, but this doesn't work well in CI/CD pipelines.
67+
validations:
68+
required: false
69+
70+
- type: textarea
71+
id: additional-context
72+
attributes:
73+
label: Additional Context
74+
description: Add any other context about the feature request here.
75+
placeholder: |
76+
- This would be particularly useful for compliance documentation where revision dates are mandatory
77+
- Could potentially integrate with git history for more accurate dating
78+
validations:
79+
required: false
80+
81+
- type: dropdown
82+
id: priority
83+
attributes:
84+
label: How important is this feature to you?
85+
options:
86+
- Nice to have
87+
- Important
88+
- Critical
89+
validations:
90+
required: true

‎docs/source/configure/index.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
---
22
title: Configure Elastic Docs
33
navigation_title: Configuration reference
4-
---
4+
---
5+
6+
* [Page configuration](./page.md)
7+
* [Content-set configuration](./content-set/index.md)
8+
* [Site configuration](./site/index.md)

‎docs/source/contribute/change-browser.md‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎docs/source/contribute/change-local.md‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎docs/source/contribute/index.md‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,28 @@
11
---
22
title: Elastic Docs contribution guide
3-
navigation_title: Contribution guide
3+
navigation_title: Contribute
44
---
55

6-
Want to contribute to the Elastic documentation? You're in the right spot! Select an option below to get started:
6+
Welcome, **contributor**!
77

8-
* I just want to suggest a change --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml)
9-
* I want to make a small change to a single page --> [Update the docs in your _web browser_](change-browser.md).
10-
* I want to make a larger change or a change to multiple pages --> [Update the docs in your _code editor_](change-local.md).
8+
Whether you're a technical writer or you've only edited Elastic docs once or twice, you're a valued contributor. Every word matters!
9+
10+
## Contribute to the docs [#contribute]
11+
12+
* Simple bugs and enhancements --> [Contribute on the web](on-the-web.md)
13+
* Complex or multi-page updates --> [Contribute locally](locally.md)
14+
15+
## Report a bug
16+
17+
* It's a **documentation** problem --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md)
18+
* It's a **build tool (docs-builder)** problem --> [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml)
19+
* It's a **migration tooling** problem --> [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml)
20+
21+
## Request an enhancement
22+
23+
* Make the **documentation** better --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml)
24+
* Make our **build tool (docs-builder)** better --> [Open a docs-builder issue](https://github.com/elastic/docs-builder/issues/new?template=enhancement.yaml)
25+
26+
## Work on docs-builder
27+
28+
That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system.

‎docs/source/contribute/locally.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: Contribute locally
3+
---
4+
5+
Follow these steps to contribute to Elastic docs.
6+
* [Step 1: Install `docs-builder`](#step-one)
7+
* [Step 2: Clone the `docs-content` repository](#step-two)
8+
* [Step 3: Serve the Documentation](#step-three)
9+
* [Step 4: Open a PR](#step-three)
10+
11+
## Step 1: Install `docs-builder` [#step-one]
12+
13+
::::{tab-set}
14+
15+
:::{tab-item} macOS
16+
17+
### macOS
18+
19+
1. **Download the Binary:**
20+
Download the latest macOS binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
21+
```sh
22+
curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip
23+
```
24+
25+
2. **Extract the Binary:**
26+
Unzip the downloaded file:
27+
```sh
28+
unzip docs-builder-mac-arm64.zip
29+
```
30+
31+
3. **Run the Binary:**
32+
Use the `serve` command to start serving the documentation at http://localhost:5000. The path to the docset.yml file that you want to build can be specified with `-p`:
33+
```sh
34+
./docs-builder serve -p ./path/to/docs
35+
```
36+
37+
:::
38+
39+
:::{tab-item} Windows
40+
41+
### Windows
42+
43+
1. **Download the Binary:**
44+
Download the latest Windows binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
45+
```sh
46+
Invoke-WebRequest -Uri https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip -OutFile docs-builder-win-x64.zip
47+
```
48+
49+
2. **Extract the Binary:**
50+
Unzip the downloaded file. You can use tools like WinZip, 7-Zip, or the built-in Windows extraction tool.
51+
```sh
52+
Expand-Archive -Path docs-builder-win-x64.zip -DestinationPath .
53+
```
54+
55+
3. **Run the Binary:**
56+
Use the `serve` command to start serving the documentation at http://localhost:5000. The path to the docset.yml file that you want to build can be specified with `-p`:
57+
```sh
58+
.\docs-builder serve -p ./path/to/docs
59+
```
60+
61+
:::
62+
63+
:::{tab-item} Linux
64+
65+
### Linux
66+
67+
1. **Download the Binary:**
68+
Download the latest Linux binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
69+
```sh
70+
wget https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-linux-x64.zip
71+
```
72+
73+
2. **Extract the Binary:**
74+
Unzip the downloaded file:
75+
```sh
76+
unzip docs-builder-linux-x64.zip
77+
```
78+
79+
3. **Run the Binary:**
80+
Use the `serve` command to start serving the documentation at http://localhost:5000. The path to the docset.yml file that you want to build can be specified with `-p`:
81+
```sh
82+
./docs-builder serve -p ./path/to/docs
83+
```
84+
85+
:::
86+
87+
::::
88+
89+
## Clone the `docs-content` Repository [#step-two]
90+
91+
Clone the `docs-content` repository to a directory of your choice:
92+
```sh
93+
git clone https://github.com/elastic/docs-content.git
94+
```
95+
96+
## Serve the Documentation [#step-three]
97+
98+
1. **Navigate to the cloned repository:**
99+
```sh
100+
cd docs-content
101+
```
102+
103+
2. **Run the Binary:**
104+
Use the `serve` command to start serving the documentation at http://localhost:5000. The path to the `docset.yml` file that you want to build can be specified with `-p`:
105+
```sh
106+
# macOS/Linux
107+
./docs-builder serve -p ./migration-test
108+
109+
# Windows
110+
.\docs-builder serve -p .\migration-test
111+
```
112+
113+
Now you should be able to view the documentation locally by navigating to http://localhost:5000.
114+
115+
## Step 4: Open a PR [#step-four]
116+
117+
Open a PR. Good luck.
118+
119+
## Step 5: View on elastic.co/docs
120+
121+
soon...

‎docs/source/contribute/on-the-web.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Contribute on the web
3+
---
4+
5+
:::{warning}
6+
This feature is not supported yet. See [#171](https://github.com/elastic/docs-builder/issues/171) for more information.
7+
:::
8+
9+
1. On the right side of the page you want to edit, select **Edit this page**.
10+
1. Do something on GitHub.
11+
1. Take the dog for a walk.
12+
1. Success!

‎docs/source/development/link-validation.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Link validation
3+
---
4+
5+
* See the [RFC](https://docs.google.com/document/d/1fZNeJCVLKu19s4WIKkkqrHyE9YlWQHNed94Y_V7ofRI/edit?tab=t.0#heading=h.z8tixe192fr4).
6+
* Infrastructure lives in [docs-infra](https://github.com/elastic/docs-infra).
7+
8+
The mermaid chart below is currently unsupported.
9+
10+
```
11+
flowchart TD
12+
subgraph **Repository Build Process**
13+
direction LR
14+
subgraph Repositories
15+
A[Repository A] --> Z1
16+
B[Repository B] --> Z2
17+
C[Repository C] --> Z3
18+
Z1[Link validation process]
19+
Z2[Link validation process]
20+
Z3[Link validation process]
21+
end
22+
Z1 & Z2 & Z3 -->|If validation succeeds| E[Generate links.json]
23+
E -->|Extract external links and add to _external_links_ array| H
24+
H[Upload updated links.json to S3]
25+
end
26+
27+
subgraph AWS **Link Index**
28+
H --> I[Amazon S3 Bucket]
29+
I --> J[CloudFront Distribution]
30+
end
31+
32+
subgraph Assembler
33+
J --> X["Validate links and build docs (TBD)"]
34+
end
35+
36+
subgraph **Link validation process**
37+
subgraph Changes to md files
38+
Q[Add External Links] --> K
39+
R[Remove Markdown Files] --> K
40+
end
41+
K[Docs build kicks off]
42+
K --> L[Download links.json files from CloudFront]
43+
L --> M{Link Validation}
44+
M -->|All Links Valid| N[Build Succeeds]
45+
M -->|Broken Links Found| O[Build Fails]
46+
end
47+
48+
J --> L
49+
50+
style N fill:#a3d9a5,color:#333
51+
style O fill:#f8a5a5,color:#333
52+
```

‎docs/source/development/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
toc:
22
- file: index.md
3+
- file: link-validation.md

0 commit comments

Comments
 (0)