Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: clarify documentation process #1410

Merged
merged 4 commits into from
Feb 1, 2022
Merged

fix: clarify documentation process #1410

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ef51019
fix: clarify documentation process
wtrocki Feb 1, 2022
da6bc8e
Update CONTRIBUTING.md
wtrocki Feb 1, 2022
be0c3be
Update CONTRIBUTING.md
wtrocki Feb 1, 2022
02b4514
Update CONTRIBUTING.md
wtrocki Feb 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 22 additions & 6 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,23 +100,39 @@ rhoas login --api-gateway=http://localhost:8000

## Internationalization

All text strings are placed in `./pkg/localize/locales` directory.
All text strings are placed in `./pkg/core/localize/locales/en` directory containing `.toml` files.
This files are used in:
wtrocki marked this conversation as resolved.
Show resolved Hide resolved

- CLI itself - all printed messages/strings
- generation of the downstream and upstream documentation

This directory contains number of `toml` files that are used for:

1. Command structure that is later generated as documentation
2. Command output and error messages returned by specific commands that aren't included in the generated documentation.

Each time we change any strings in comman structure (1) we should regenerate markdown documentation files and push them with the PR.
wtrocki marked this conversation as resolved.
Show resolved Hide resolved
Downstream changes are regenerated on release.

## Documentation

The main CLI documentation source files are stored in the `./pkg/localize/locales/en/cmd/` directory.
The main CLI documentation source files are stored in the `./pkg/corelocalize/locales/en/cmd/` directory.
wtrocki marked this conversation as resolved.
Show resolved Hide resolved

The CLI documentation output is generated in the `./docs` directory.
The CLI documentation output is generated in the `./docs` directory as markdown files that are published as https://appservices.tech website.

### Generating documentation
### Generating website documentation

#### `make generate-docs`

After running the command, the documentation should be generated in AsciiDoc format.
After running the command, the documentation should be generated in markdown format.

#### Generating downstream (asciidocs) documentation

#### `make generate-modular-docs`
`make generate-modular-docs`

After running the command, the `dist` directory will contain the documentation conforming to the modular docs specification.
Developers do not need to generate that documentation themselves. We have github action that generates documentation automatically
into `modular-docs` branch on each CLI release.

## Best practices

Expand Down