More docs updates

README.md

@@ -7,11 +7,11 @@ This repository is host to:
 * *`docs-builder`* command line tool to generate single doc-sets (13mb native code, no dependencies)
 * *`docs-assembler`* command line tool to assemble all the doc sets. (IN PROGRESS)
 * `elastic/docs-builder@main` Github Action to build and validate a repositories documentation
-
+* *`docs-generator`* command line tool to deterministically generate a docset and incremental updates to generated content
 
 ## Command line interface
 
-```
+```bash
 $ docs-builder --help
 Usage: [command] [options...] [-h|--help] [--version]
 
@@ -26,7 +26,7 @@ Options:
 Commands:
   generate    Converts a source markdown folder or file to an output folder
   serve       Continuously serve a documentation folder at http://localhost:5000.
-	File systems changes will be reflected without having to restart the server.
+    File systems changes will be reflected without having to restart the server.
 ```
 
 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
 ## Run without docker
 
 You can use the .NET CLI to publish a self-contained `docs-builder` native code
-binary. (On my M2 Pro mac the binary is currently 13mb)
+binary. (On my M2 Pro mac the binary is currently 16mb)
 
 Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run:
 
 ```bash
-dotnet publish "src/docs-builder/docs-builder.csproj" -c Release -o .artifacts/publish \
-    --self-contained true /p:PublishTrimmed=true /p:PublishSingleFile=false /p:PublishAot=true -a arm64
+dotnet publish "src/docs-builder/docs-builder.csproj"
 ```
 
-**Note**: `-a` should be the machine's CPU architecture
-
-The resulting binary `./.artifacts/publish/docs-builder` will run on machines without .NET installed
+The resulting binary `./.artifacts/publish/docs-builder/release/docs-builder` will run on machines without .NET installed.
 
 # Performance
 
 To test performance it's best to build the binary and run outside of docker:
 
-For refence here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to
+For reference here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to
 existing surveyed tools

docs/source/contribute/index.md

@@ -0,0 +1,14 @@
+---
+title: Elastic Docs contribution guide
+navigation_title: Contribution guide
+---
+
+Want to contribute to the Elastic documentation? You're in the right spot!
+
+1. Install dependencies
+2. Clone repositories
+3. Make changes
+4. Open a Pull Request
+5. Work with CI
+6. Get approvals and merge
+7. View your changes live on elastic.co

docs/source/docset.yml

@@ -19,6 +19,12 @@ exclude:
   - '_*.md'
 toc:
   - file: index.md
+  - folder: migration
+    children:
+      - file: index.md
+  - folder: contribute
+    children:
+      - file: index.md
   - folder: syntax
     children:
       - file: index.md

docs/source/index.md

@@ -28,7 +28,7 @@
 Commands:
   generate    Converts a source markdown folder or file to an output folder
   serve       Continuously serve a documentation folder at http://localhost:5000.
-	File systems changes will be reflected without having to restart the server.
+    File systems changes will be reflected without having to restart the server.
 ```
 
 In the near term native code will be published by CI for the following platforms
@@ -44,7 +44,8 @@
 For now you can run the tool locally through `docker run`
 
 ```bash
-docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" ghcr.io/elastic/docs-builder:edge
+docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
+  ghcr.io/elastic/docs-builder:edge
 ```
 
 This ensures `.git`/`docs` and `.artifacts` (the default output directory) are mounted.
@@ -54,15 +55,17 @@
 to force a new compilation.
 
 ```bash
-docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" ghcr.io/elastic/docs-builder:edge --force
+docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
+  ghcr.io/elastic/docs-builder:edge --force
 ```
 
 #### Live mode
 
 Through the `serve` command you can continuously and partially compile your documentation.
 
 ```bash
-docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" --expose 8080 ghcr.io/elastic/docs-builder:edge serve
+docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
+  -p 8080:8080 ghcr.io/elastic/docs-builder:edge serve
 ```
 
 Each page is compiled on demand as you browse http://localhost:8080 and is never cached so changes to files and
@@ -124,24 +127,26 @@
 https://github.com/elastic/{your-repository}/settings/pages
 
 ---
-![_static/img/github-pages.png](_static/img/github-pages.png)
+![docs/source/_static/img/github-pages.png](docs/source/_static/img/github-pages.png)
 
 ---
 
 ## Run without docker
 
-If you have dotnet 8 installed you can use its CLI to publish a self-contained `docs-builder` native code
+You can use the .NET CLI to publish a self-contained `docs-builder` native code
 binary. (On my M2 Pro mac the binary is currently 16mb)
 
+Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run:
+
 ```bash
-$ dotnet publish "src/docs-builder/docs-builder.csproj"
+dotnet publish "src/docs-builder/docs-builder.csproj"
 ```
 
-The resulting binary `./.artifacts/publish/docs-builder/release/docs-builder` will run on machines without .NET installed
+The resulting binary `./.artifacts/publish/docs-builder/release/docs-builder` will run on machines without .NET installed.
 
 # Performance
 
 To test performance it's best to build the binary and run outside of docker:
 
-For refence here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to
+For reference here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to
 existing surveyed tools

docs/source/migration/index.md

@@ -0,0 +1,13 @@
+---
+title: Migrate from Asciidoc to V3
+navigation_title: Migration guide
+---
+
+How to migrate content from Asciidoc to V3.
+
+1. Clone https://github.com/elastic/adoc-to-md
+2. Run the migration tool
+3. Copy the output to the appropriate directory in https://github.com/elastic/docs-content
+4. Update the `docset.yml` file to reflect the new IA of the content set
+5. Build your changes with https://github.com/elastic/docs-builder
+6. Open a PR and merge your changes

docs/source/syntax/tables.md

@@ -29,41 +29,3 @@ You can use the GFM table syntax to create a table:
 | ------- | --------------- |
 | USA     | Washington D.C. |
 | Canada  | Ottawa          |
-
-% Neither of these work
-% ## `{table}` Directive
-%
-% You can use the `table` directive which gives you configuration captions such as caption and alignment.
-%
-% ```{table} Countries and their capitals
-% :widths: auto
-% :align: right
-%
-% | Country | Capital         |
-% | ------- | --------------- |
-% | USA     | Washington D.C. |
-% | Canada  | Ottawa          |
-% ``` -->
-%
-% <!-- ## `{list-table}` Directive
-%
-% You can also use the `list-table` directive to create a table from data.
-%
-% ```{list-table} Frozen Delights!
-% :widths: 15 10 30
-% :header-rows: 1
-%
-% *   - Treat
-%     - Quantity
-%     - Description
-% *   - Albatross
-%     - 2.99
-%     - On a stick!
-% *   - Crunchy Frog
-%     - 1.49
-%     - If we took the bones out, it wouldn't be
-%  crunchy, now would it?
-% *   - Gannet Ripple
-%     - 1.99
-%     - On a stick!
-% ```