137123294a
## Description Auto-generate CLI docs in docs dev tooling. * Add new Makefile target to rebuild the `mdgen` binary, only if needed. This helps with slow in container builds. Relies on host caching of both modules and the actual binary. This approach is probably not suitable for the actual docs CI build. * Actual generation is fast and done every time when using relevant docs dev tooling commands. NOTE: .gitignore may need to be adjusted if we switch to creating the CLI docs as part of build and tooling as opposed to the current automated PR with changes. ## Type of change Please check the type of change your PR introduces: - [x] 🌻 Feature - [ ] 🐛 Bugfix - [x] 🗺️ Documentation - [ ] 🤖 Test - [ ] 🐹 Trivial/Minor ## Issue(s) ## Test Plan <!-- How will this be tested prior to merging.--> - [x] 💪 Manual - [ ] ⚡ Unit test - [ ] 💚 E2E
70 lines
1.6 KiB
Markdown
70 lines
1.6 KiB
Markdown
# Corso documentation
|
|
|
|
Corso documentation uses [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
|
|
[Mermaid](https://mermaid-js.github.io/mermaid/) provides support for native diagrams in Markdown.
|
|
|
|
## Requirements
|
|
|
|
Developing documentation for Corso requires the following tools on your machine:
|
|
|
|
- `make`
|
|
- Docker
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
make buildimage
|
|
```
|
|
|
|
## Live documentation development
|
|
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
This command starts a local development server within the Docker container and will expose docs at [http://localhost:3000](http://localhost:3000).
|
|
|
|
## Generating Corso CLI docs
|
|
|
|
```bash
|
|
make genclidocs
|
|
```
|
|
|
|
Corso's CLI documents are auto-generated. This command explicitly triggers generating these docs. This step will happen
|
|
automatically for the other commands where this is relevant.
|
|
|
|
## Building static documentation
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
This command generates static content into the `build` directory for integration with any static contents hosting service.
|
|
|
|
## Style and linting
|
|
|
|
```bash
|
|
# Lint all docs
|
|
make dockercheck
|
|
# Lint specific files and/or folders
|
|
make dockercheck VALE_TARGET="README.md docs/concepts"
|
|
```
|
|
|
|
This command will lint all Markdown files and check them for style issues using the Docker container
|
|
|
|
```bash
|
|
make check
|
|
```
|
|
|
|
Same as `make dockercheck` but runs locally. Requires `vale` to be installed.
|
|
|
|
## Documentation platform development
|
|
|
|
```bash
|
|
make shell
|
|
```
|
|
|
|
Use this command to interactively (and temporarily!) change the contents or
|
|
configuration of the live documentation container image (for example, when
|
|
experimenting with new plugins).
|