Open bredamc opened 1 year ago
Hi, @rohennes.
Hi @bredamc, I raised this issue in today's Modular Documentation Steering Committee meeting and got support for it from @emmurphy1 and @mjahoda.
@rolfedh That's great, many thanks for raising the issue and letting me know the result!
The AsciiDoc Vale rules are an attempt to highlight potential issues with AsciiDoc syntax that can cause problems in output, unclosed tables, incorrect ifdefs, etc. You could consider it like an imperfect and (very) limited AsciiDoc Parser. Note that a lot of these validations are done by default with the asciidoctor.js validation in the VS Code plugin.
The OpenShiftAsciiDoc are probably closer to what a Mod Docs rule set would look like. These are project-specific AsciiDoc usage guidelines.
Click into the rules above to see a one-liner describing what the rule catches.
Hey Rolfe, +1 to Aidan's comments. AsciiDoc rules are aimed at basic syntax validation. It is a vanilla rule set that can be used inside/outside of Red Hat, so isn't based on any Red Hat specific guidelines like the mod docs guidelines. For more custom metadata, we created the OpenShiftAsciiDoc rules. I don't think you could see them as a checklist for mod docs, although they are complimentary.
A vale rule set for mod docs might be possible, but probably fairly limited. You could have a rule for the following:
{context}
(in modules only)It may be more effort than it's worth though. You'd also need to configure you .vale.ini to ensure module or assembly specific mod-docs rules applied only to assemblies/modules. Bit of a headache...
A few years ago, I started a Vale style for exactly this which I recently decided to revive. I do not think it is mature enough and some of the changes I have implemented locally are maybe not suitable for all projects, but I currently have the following functionality:
{context}
attribute{context}
attribute a new valueleveloffset
do not add more than one level (not suitable for projects that do not follow the tree-like content structure)Unpushed I also have experimental version of rules that:
subs="quotes"
enabledWow! This is a great start, @jhradilek.
If you're interested, the newdoc tool that @msuchane created for generating new mod doc files has a deprecated -validate
option. I wonder if he has some insights to that might be useful to your project.
For background:
[rdlugyhe@rdlugyhe-thinkpadt14sgen2i rhbq-quarkus]$ newdoc --help
Generate pre-populated module files formatted with AsciiDoc that are used in Red Hat and Fedora
documentation.
Usage: newdoc -a TITLE... -c TITLE... -p TITLE... -r TITLE... -s TITLE... [-i TITLE] -l FILE... [-M]
[-E] [-P] [-A] [-T DIRECTORY] [-v | -q]
Available options:
Generate or validate files:
-a, --assembly <TITLE> Create an assembly file
-c, --concept <TITLE> Create a concept module
-p, --procedure <TITLE> Create a procedure module
-r, --reference <TITLE> Create a reference module
-s, --snippet <TITLE> Create a snippet file
-i, --include-in <TITLE> Create an assembly that includes the other specified modules
-l, --validate <FILE> DEPRECATED: Validate (lint) an existing module or assembly file
^^^^^^^^^^^^^^^^^^^^^^^^^^
Common options:
-M, --comments Generate the file with explanatory comments
-E, --no-examples Generate the file without any example, placeholder content
-P, --no-file-prefixes Do not use module type prefixes (such -l, --validate <FILE> DEPRECATED: Validate (lint) an existing module or assembly fileas `proc_`) in file names
-A, --anchor-prefixes Add use module type prefixes (such as `proc_`) in AsciiDoc anchors
-T, --target-dir <DIRECTORY> Save the generated files in this directory
-v, --verbose Display additional, debug messages
-q, --quiet Hide info-level messages. Display only warnings and errors
-h, --help Prints help information
-V, --version Prints version information
In https://github.com/redhat-documentation/modular-docs/pull/211#issuecomment-1719494951, which is very much WIP, @mjahoda proposes having an abbreviated checklist in addition to the comprehensive one.
For simplicity and ease of maintenance, I propose having a single checklist with two parts:
The checklist and tooling completement each other:
We'll work to ensure that the mod docs standard, checklist, and tooling all align with one another.
@jhradilek, I created an issue for the Mod Docs community to discuss the Vale Style for Mod Docs: https://github.com/redhat-documentation/modular-docs/issues/212
If you're interested, the newdoc tool that @msuchane created for generating new mod doc files has a deprecated
-validate
option. I wonder if he has some insights to that might be useful to your project.
The validation feature in newdoc
only ever tested Pantheon 2 and Jupiter requirements. Now that we're moving to a different publishing platform, the tests are obsolete, so I'm removing them. There was very little in the newdoc
validation suite that could check the modularity: maybe a test if modules include other modules.
@rolfedh the checklist is a great start. I believe the original request was for a checklist that writers can use when reviewing modularized content. The discussion around vale is really great as well, and it possible it would be fantastic to get check in there. However, I think these are two separate projects. I made a few comments in the MR. In general, I think we need to make the checks more specific.
The Modular documentation reference guide and associated templates are very useful when learning about mod docs, thank you!
Do we also have a Modular Documentation checklist? Such a document would be very useful for those who are new to mod docs, and for peer reviews by reviewers who are not familiar with all of the mod doc rules.