Skip to content

Commit 260bac3

Browse files
bmorelli25bmorelli25
authored
More docs updates (#136)
1 parent 79a67ef commit 260bac3

File tree

21 files changed

+311
-56
lines changed

21 files changed

+311
-56
lines changed

‎README.md‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@ This repository is host to:
77
* *`docs-builder`* command line tool to generate single doc-sets (13mb native code, no dependencies)
88
* *`docs-assembler`* command line tool to assemble all the doc sets. (IN PROGRESS)
99
* `elastic/docs-builder@main` Github Action to build and validate a repositories documentation
10-
10+
* *`docs-generator`* command line tool to deterministically generate a docset and incremental updates to generated content
1111

1212
## Command line interface
1313

14-
```
14+
```bash
1515
$ docs-builder --help
1616
Usage: [command] [options...] [-h|--help] [--version]
1717

@@ -26,7 +26,7 @@ Options:
2626
Commands:
2727
generate Converts a source markdown folder or file to an output folder
2828
serve Continuously serve a documentation folder at http://localhost:5000.
29-
File systems changes will be reflected without having to restart the server.
29+
File systems changes will be reflected without having to restart the server.
3030
```
3131

3232
In the near term native code will be published by CI for the following platforms
@@ -132,22 +132,19 @@ https://github.com/elastic/{your-repository}/settings/pages
132132
## Run without docker
133133

134134
You can use the .NET CLI to publish a self-contained `docs-builder` native code
135-
binary. (On my M2 Pro mac the binary is currently 13mb)
135+
binary. (On my M2 Pro mac the binary is currently 16mb)
136136

137137
Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run:
138138

139139
```bash
140-
dotnet publish "src/docs-builder/docs-builder.csproj" -c Release -o .artifacts/publish \
141-
--self-contained true /p:PublishTrimmed=true /p:PublishSingleFile=false /p:PublishAot=true -a arm64
140+
dotnet publish "src/docs-builder/docs-builder.csproj"
142141
```
143142

144-
**Note**: `-a` should be the machine's CPU architecture
145-
146-
The resulting binary `./.artifacts/publish/docs-builder` will run on machines without .NET installed
143+
The resulting binary `./.artifacts/publish/docs-builder/release/docs-builder` will run on machines without .NET installed.
147144

148145
# Performance
149146

150147
To test performance it's best to build the binary and run outside of docker:
151148

152-
For refence here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to
149+
For reference here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to
153150
existing surveyed tools

‎docs/source/configure/content-set/attributes.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Attributes
3+
---
4+
5+
tbd

‎docs/source/configure/content-set/file-structure.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: File structure
3+
---
4+
5+
tbd

‎docs/source/configure/content-set/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Content set configuration
3+
navigation_title: Content set
4+
---
5+
6+
Now we'll zoom into the AsciiDoc book level, and explore the V3 equivalent: content sets. At the book level, the system consists of:
7+
8+
| System property | Asciidoc | V3 |
9+
| -------------------- | -------------------- | -------------------- |
10+
| **Content source files** --> A whole bunch of markup files as well as any other assets used in the docs (for example, images, videos, and diagrams). | **Markup**: AsciiDoc files **Assets**: Images, videos, and diagrams | **Markup**: MD files **Assets**: Images, videos, and diagrams |
11+
| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the `conf.yaml` file)) | TBD |

‎docs/source/configure/content-set/navigation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Navigation
3+
---
4+
5+
tbd

‎docs/source/configure/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Configure Elastic Docs
3+
navigation_title: Configuration reference
4+
---

‎docs/source/configure/page.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Page configuration
3+
navigation_title: Page
4+
---
5+
6+
tbd
7+
8+
go into frontmatter here?
9+
10+
for now, see [frontmatter](../syntax/frontmatter.md).

‎docs/source/configure/site/content.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Content config
3+
---
4+
5+
In both the AsciiDoctor- and V3-based system, there is site-wide configuration where you list all content sources, where to find those sources, and in what order they should be added to the site.
6+
7+
In the AsciiDoctor system, this all happens in one YAML file in the /docs repo. In the V3 system, this ...
8+
9+
## AsciiDoctor conf.yml
10+
11+
In the AsciiDoctor-powered site, content configuration at the site level is done in the [`conf.yaml`](https://github.com/elastic/docs/blob/master/conf.yaml) file in the elastic/docs repo. In the `conf.yml` file, the configuration information for all books are listed in this one file. Here's the example of what it looks like to configure a single book:
12+
13+
```yaml
14+
- title: Machine Learning
15+
prefix: en/machine-learning
16+
current: *stackcurrent
17+
index: docs/en/stack/ml/index.asciidoc
18+
branches: [ {main: master}, 8.9, 8.8, 8.7, 8.6, 8.5, 8.4, 8.3, 8.2, 8.1, 8.0, 7.17, 7.16, 7.15, 7.14, 7.13, 7.12, 7.11, 7.10, 7.9, 7.8, 7.7, 7.6, 7.5, 7.4, 7.3, 7.2, 7.1, 7.0, 6.8, 6.7, 6.6, 6.5, 6.4, 6.3 ]
19+
live: *stacklive
20+
chunk: 1
21+
tags: Elastic Stack/Machine Learning
22+
subject: Machine Learning
23+
sources:
24+
-
25+
repo: stack-docs
26+
path: docs/en/stack
27+
-
28+
repo: elasticsearch
29+
path: docs
30+
-
31+
repo: docs
32+
path: shared/versions/stack/{version}.asciidoc
33+
-
34+
repo: docs
35+
path: shared/attributes.asciidoc
36+
-
37+
repo: docs
38+
path: shared/settings.asciidoc
39+
```
40+
41+
## V3 configuration
42+
43+
TO DO

‎docs/source/configure/site/img/site-level-asciidoctor.png‎

176 KB
Loading

‎docs/source/configure/site/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Site configuration
3+
navigation_title: Site
4+
---
5+
6+
Start by understanding how the new V3 system works at the site level compared to how our custom AsciiDoctor system works. The system consists of:
7+
8+
9+
| System property | Asciidoc | V3 |
10+
| -------------------- | -------------------- | -------------------- |
11+
| **Content sources** --> Collections of markup files containing doc content. These are split up across many docs repos. | _Books_ | _Content sets_ |
12+
| **Content configuration** --> A way to specify where to find those content sources, and in what order they should be added to the site. | Configuration file ([`conf.yml`](https://github.com/elastic/docs/blob/master/conf.yaml) in elastic/docs) | Config file location TBD |
13+
| **Cross-site values** --> Key-value pairs that should be substituted across all sources as web pages are built. | Shared attributes ([`shared/`](https://github.com/elastic/docs/tree/master/shared) in elastic/docs) | Shared attrs file TBD |
14+
| **Docs build tool** --> An engine used to take the markup in the content sources and transform it into web pages. | Customized version of AsciiDoctor (lives in [**elastic/docs**](https://github.com/elastic/docs)) | Customized doc builder using open source tools (lives in [**elastic/docs-builder**](https://github.com/elastic/docs-builder)) |
15+
16+
Where these pieces live and what format they are in varies between the two systems, but they generally achieve the same goal.
17+
18+
## Asciidoc
19+
20+
![site-level config in the asciidoc system](./img/site-level-asciidoctor.png)
21+
22+
## V3
23+
24+
DIAGRAM NEEDED

0 commit comments

Comments
 (0)