New style Documentation #4336
New style Documentation #4336
Conversation
+ minor refactoring
# Conflicts: # docs/mp/metrics/02_micrometer.adoc # docs/se/metrics/02_micrometer.adoc
| === Custom Health Root Path and Port | ||
|
|
||
| You can specify a custom port and root context for the root health endpoint path. | ||
| However, you cannot use different ports, such as http://localhost:8080/myhealth and http://localhost:8081/myhealth/live. | ||
| Likewise, you cannot use different paths, such as http://localhost:8080/health and http://localhost:8080/probe/live. | ||
|
|
||
| The example below will change the root path. | ||
|
|
||
| [source,yaml] | ||
| .Create a file named `application.yaml` in the `resources` directory with the following contents: | ||
| ---- | ||
| health: | ||
| web-context: "myhealth" // <1> | ||
| ---- | ||
| <1> The web-context specifies a new root path for the health endpoint. | ||
|
|
There was a problem hiding this comment.
We should be able to remove this section and rely on the generated config doc instead.
Speaking of that, we will need to change either config annotations in health or in service-common or the tool or perhaps all to support inheritance. The HealthSupport.Builder extends HelidonRestServiceSupport.Builder so the config doc for health will need to incorporate the doc from the superclass. The JSON file the health build generates does not include the superclass config info so something is not quite right. This should be a separate issue from the doc update itself though, except eventually for changing this to include the generated config doc.
| Configuration properties, values and description | ||
|
|
||
| |=== | ||
| |Property | Values | Description | ||
|
|
||
| |health:web-context | ||
| |`String` | ||
| | The endpoint name on which the health context is propagated | ||
|
|
||
| |=== |
There was a problem hiding this comment.
To be replaced by an include for the generated config doc.
|
I wouldn't put |
This is a draft proposal for the New Style Documentation.
I will be clear, it DIRTY and a lot has to be done for it to become production ready.
Current proposal is based on the document discussed 02.05.2022.
I will also be clear, that current documentation did not follow any specific rules and structure, so normalising it is not a trivial task.
Each chapter except mp/CDI, mp/AOP, mp/Config, se/Webserver, se/AOP, se/Config has been reformatted to follow the structure:
For the chapters mentioned above, as some of them are in the core of everything, additional discussion should be made.
Proposed structure for Helidon MP:
Proposed structure for Helidon SE:
Each reformatted chapter was done with my personal view of the things and may be controversial. Need to be checked by colleagues with deeper knowledge in particular areas.
In all of the chapters, the missing areas are marked with
TODO:In all of the chapters, the
Referencesubchapter is considered to be generated (otherwise, all config values have to be manually checked).A special
Helidon Docboard is used to track documentation changes https://github.com/oracle/helidon/projects/22Tasks for each documentation items are created.
A lot code is reused from the guides, but they are still kept in the
docstructure.The
sitegen.ymlis also reformatted, but as the generator has its own limitations with include depth additional discussion is possible.