Skip to content

Commit e784ad1

Browse files
JordonPhillipsJordonPhillips
committed
Update readme
1 parent fa5d3cb commit e784ad1

File tree

1 file changed

+124
-2
lines changed

1 file changed

+124
-2
lines changed

‎README.md‎

Lines changed: 124 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,129 @@
11
## Smithy DocGen
22

3-
Smithy build plugin to generate API documentation from models authored in [Smithy](https://smithy.io) IDL.
3+
Smithy build plugin to generate API documentation from models authored in
4+
[Smithy](https://smithy.io) IDL.
5+
6+
NOTE: this project is currently in a pre-release state. Interfaces and output
7+
formatting may change before full release.
8+
9+
### Supported Formats
10+
11+
The output format can be selected with the `format` configuration option. The
12+
example below demonstrtates selecting a plain markdown output format:
13+
14+
```json
15+
{
16+
"version": "1.0",
17+
"projections": {
18+
"plain-markdown": {
19+
"plugins": {
20+
"docgen": {
21+
"service": "com.example#MyService",
22+
"format": "markdown"
23+
}
24+
}
25+
}
26+
}
27+
}
28+
```
29+
30+
By default, two formats are currently supported: `markdown` and
31+
`sphinx-markdown`. The `markdown` format renders docs as plain
32+
[CommonMark](https://commonmark.org), while `sphinx-commonmark` creates a
33+
[Sphinx](https://www.sphinx-doc.org/) markdown project that gets rendered to
34+
HTTP. `sphinx-markdown` is used by default.
35+
36+
The generator is designed to allow for different output formats by supplying a
37+
new
38+
[DocWriter](https://github.com/smithy-lang/smithy-docgen/blob/main/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/DocWriter.java)
39+
via a
40+
[DocIntegration](https://github.com/smithy-lang/smithy-docgen/blob/main/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocIntegration.java).
41+
42+
#### sphinx-markdown
43+
44+
The `sphinx-markdown` format uses Sphinx's markdown support provided by
45+
[MySt](https://myst-parser.readthedocs.io/en/latest/), which builds on top of
46+
CommonMark. By default, it will render the generated markdown into HTML as long
47+
as Python 3 is found on the path.
48+
49+
* `format` (default: `html`) - The
50+
[sphinx output format](https://www.sphinx-doc.org/en/master/usage/builders/index.html).
51+
* `theme` (default: [`furo`](https://github.com/pradyunsg/furo)) - The theme to
52+
use for sphinx. If this is changed, the new theme will likely need to be added
53+
to the `extraDependencies` list.
54+
* `extraDependencies` (default: `[]`) - A list of additional dependencies to be
55+
added to the `requirements.txt` file, which is installed before building the
56+
documentation.
57+
* `extraExtensions` (default: `[]`) - A list of additional sphinx extentions to
58+
add to the sphinx extensions list in `conf.py`. Any additional extensions will
59+
likely need to be added to the `extraDependencies` list.
60+
* `autoBuild` (default: `true`) - Whether to automatically render the
61+
documentation to HTML. You may wish to disable autobuild if you want to add
62+
additional documentation to the project before building, such as hand-written
63+
guides.
64+
65+
The following example `smithy-build.json` demonstrates configuring the
66+
`sphinx-markdown` format.
67+
68+
```json
69+
{
70+
"version": "1.0",
71+
"projections": {
72+
"sphinx-markdown": {
73+
"plugins": {
74+
"docgen": {
75+
"service": "com.example#DocumentedService",
76+
"format": "sphinx-markdown",
77+
"integrations": {
78+
"sphinx": {
79+
"format": "dirhtml",
80+
"autoBuild": false
81+
}
82+
}
83+
}
84+
}
85+
}
86+
}
87+
}
88+
```
89+
90+
### Trait Support
91+
92+
Currently, most prelude (`smithy.api`) traits are supported, or deliberately
93+
excluded where not relevant to customer documentation. Trait information is
94+
easily added using Smithy's
95+
[interceptor](https://github.com/smithy-lang/smithy/blob/main/smithy-utils/src/main/java/software/amazon/smithy/utils/CodeInterceptor.java)
96+
system. Most trait information is added using interceptors, the implementations
97+
of which can be found in the
98+
[interceptors](https://github.com/smithy-lang/smithy-docgen/tree/main/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/interceptors)
99+
package.
100+
101+
Auth traits are automatically supported as part of the service's auth list,
102+
where the trait's docs are used by default. More context can be added using
103+
the same interceptors that are run on normal shapes.
104+
105+
#### Traits Missing Support
106+
107+
The following prelude traits and trait categories are currently unsupported. All
108+
traits outside of the prelude are unsupported, with the exception of auth traits
109+
which have default support.
110+
111+
* Protocol Traits - These should get a similar treatment to auth traits, where a
112+
dedicated section is created for them and documentation is added without
113+
needing to add explicit support. Each protocol also needs to be able to register
114+
an example generator.
115+
* [Streaming Traits](https://smithy.io/2.0/spec/streaming.html)
116+
* [cors](https://smithy.io/2.0/spec/http-bindings.html#smithy-api-cors-trait)
117+
* [examples](https://smithy.io/2.0/spec/documentation-traits.html#smithy-api-examples-trait) -
118+
The sections and wrapping for these are created, and currently there's a
119+
stub that simply places the values of example inputs and outputs inside the
120+
example blocks. An interface needs to be created for code generators to
121+
actually integrate into this. Updates to directed codegen will likely be
122+
needed to make this feasible. Protocols will need to implement this also.
123+
* [mediaType](https://smithy.io/2.0/spec/protocol-traits.html#smithy-api-mediatype-trait)
124+
* [references](https://smithy.io/2.0/spec/resource-traits.html#smithy-api-references-trait)
125+
* [requestCompression](https://smithy.io/2.0/spec/behavior-traits.html#smithy-api-requestcompression-trait)
126+
* [retryable](https://smithy.io/2.0/spec/behavior-traits.html#smithy-api-retryable-trait)
4127

5128
## Security
6129

@@ -9,4 +132,3 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform
9132
## License
10133

11134
This project is licensed under the Apache-2.0 License.
12-

0 commit comments

Comments
 (0)