Build out warnings infrastructure #671
Comments
nik9000
added a commit
to nik9000/docs
that referenced
this issue
Mar 7, 2019
This adds the concept of "MIGRATION warnings" that are specifically around migrating to Asciidoctor. By default these warnings are only enforced against the "latest" version of each book where "latest" is the first version listed in the `branches` list. The idea is that we'd like "modern" versions of the documentation to be fully Asciioctor compatible but that we won't be able to do that overnight and that we won't be able to modify very old documentation to be compatible and we will forever rely on the compatibility layer in branches that are not actively being developed. This only adds a single `MIGRATION` warning, emitted when the start of a code block doesn't match the end of a code block. These are very simple to fix and we can fix them before migrating the book to Asciidoctor. In future work we'll want to emit `MIGRATION` warnings when we use the "old" style for things like the `beta[]` macro. Since the "new" style is not compatible with Asciidoc the order of operations has to be: 1. Switch the book to Asciidoctor, suppressing the warnings for `beta[]` 2. Migrate all usages of the `beta[]` macro to the new `beta::[]` style. 3. Remove the suppression. This change doesn't have a way to suppress any `MIGRATION` warnings on the latest version of the each book. As I said above, it *always* suppresses them on older versions. When you use `./build_docs --doc` we can't tell whether you are building the latest version of a book or an older version so we assume that you are building the latest version. This is the most common thing. When you build an older version you can do ``` ./build_docs --suppress_migration_warnings --doc foo.asciidoctor ``` to suppress the `MIGRATION` warnings. Begins work on elastic#671
nik9000
added a commit
that referenced
this issue
Mar 8, 2019
This adds the concept of "MIGRATION warnings" that are specifically around migrating to Asciidoctor. By default these warnings are only enforced against the "latest" version of each book where "latest" is the first version listed in the `branches` list. The idea is that we'd like "modern" versions of the documentation to be fully Asciioctor compatible but that we won't be able to do that overnight and that we won't be able to modify very old documentation to be compatible and we will forever rely on the compatibility layer in branches that are not actively being developed. This only adds a single `MIGRATION` warning, emitted when the start of a code block doesn't match the end of a code block. These are very simple to fix and we can fix them before migrating the book to Asciidoctor. In future work we'll want to emit `MIGRATION` warnings when we use the "old" style for things like the `beta[]` macro. Since the "new" style is not compatible with Asciidoc the order of operations has to be: 1. Switch the book to Asciidoctor, suppressing the warnings for `beta[]` 2. Migrate all usages of the `beta[]` macro to the new `beta::[]` style. 3. Remove the suppression. This change doesn't have a way to suppress any `MIGRATION` warnings on the latest version of the each book. As I said above, it *always* suppresses them on older versions. When you use `./build_docs --doc` we can't tell whether you are building the latest version of a book or an older version so we assume that you are building the latest version. This is the most common thing. When you build an older version you can do ``` ./build_docs --suppress_migration_warnings --doc foo.asciidoctor ``` to suppress the `MIGRATION` warnings. Begins work on #671
|
I think #1045 is a restating of this. I didn't meant to file two issues, but I think it explains it a bit better. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Right now any warning causes the book to fail to build. This is a lovely way for things to be but as part of the transition to Asciidoctor we'd like to migrate our docs to be more "asciidoctor native". I propose we manage this process by enhancing the warnings infrastructure to allow a per-book configuration to ignore some warnings with a "ratchet" that we can "tighten" when we fix warnings. The idea here is that some book will have some warnings from the Asciidoctor conversion and those warnings shouldn't cause the book to fail to build. If someone adds docs that would create additional warnings the build should fail. If someone fixes some warnings they should be forced to "mark them fixed" so they never get worse again.
The text was updated successfully, but these errors were encountered: