You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Skydoc had a lot of problems and was becoming a major hinderance for this repo so it has been removed. A new documentation tool is in the works. I don't have any details for this but I think I will use it once it is available.
A lot of the internal and public elements of the rules are already documented but it is outdated. I suspect the new tool will work out of the box. However, this won't be the whole solution, design docs , usage tutorials and faqs cant all be inlined and extracted from the rules.
The go rules use rst for hand written documentation. I really like this approach. I have since discovered asciidoc it is functionally equivalent to rst as a better markdown but it is easier to work with (richer intellij plugin, simpler patterns and supported by github).
I wonder what output formats the new Skydoc tool will support. It would be nice to be able to weave the extracted documentation into technical documentation that is written in markdown / rst / asciidoc. It is quite valuable to have the rule contracts documented and browse-able via github without having to go to a separate website.
I'll make a start on some asciidoc -- but I need feedback on how heavily I should invest in it as I don't know what is on the horizon. The kotlin rules need a lot of documentation for users and developers alike so it's important to get to a stable documentation strategy. If you are working on bazel core, the new tool or have any insights please give your feedback.
The text was updated successfully, but these errors were encountered:
Skydoc had a lot of problems and was becoming a major hinderance for this repo so it has been removed. A new documentation tool is in the works. I don't have any details for this but I think I will use it once it is available.
A lot of the internal and public elements of the rules are already documented but it is outdated. I suspect the new tool will work out of the box. However, this won't be the whole solution, design docs , usage tutorials and faqs cant all be inlined and extracted from the rules.
The go rules use rst for hand written documentation. I really like this approach. I have since discovered asciidoc it is functionally equivalent to rst as a better markdown but it is easier to work with (richer intellij plugin, simpler patterns and supported by github).
I wonder what output formats the new Skydoc tool will support. It would be nice to be able to weave the extracted documentation into technical documentation that is written in markdown / rst / asciidoc. It is quite valuable to have the rule contracts documented and browse-able via github without having to go to a separate website.
I'll make a start on some asciidoc -- but I need feedback on how heavily I should invest in it as I don't know what is on the horizon. The kotlin rules need a lot of documentation for users and developers alike so it's important to get to a stable documentation strategy. If you are working on bazel core, the new tool or have any insights please give your feedback.
The text was updated successfully, but these errors were encountered: