tcartwright/SqlServer.Rules

Documenation builder

matthew-n opened this issue · 5 comments

matthew-n commented

We can ticket out the work.

  • powershell to extract the MD from the C# attributes, and xml comments.

Pulls from:

  • Fill out summary tag
  • FriendlyName, and IsIgnorable tags
  • ExampleMd tag with good / bad examples

Originally posted by @tcartwright in #14 (comment)

tcartwright commented

I found a build action similar enough for us to modify here:

https://github.com/jpadfield/simple-site/blob/master/.github/workflows/build.yml

tcartwright commented

holy crap. we now have a fully blown pipeline. All we need is walter to update the ..github\workflows\generate_docs.ps1 with the code to generate the md files.

It runs in order:

  • checkout
  • linter
  • build
  • tests
  • generate docs (crappy script i generated for testing, generates a README.MD file atm)
  • commit docs
  • push docs

https://github.com/tcartwright/SqlServer.Rules/runs/3267356232?check_suite_focus=true

tcartwright commented

Walter, one small change to the MD files the PS will generate. Can you add a comment at the top similar to the autogenerated classes we normally see like so?:

Example:

This file was auto generated, any manual edits could be lost the next time the file is generated.::

Like so. or however comments are done in markdown:

^^^ Comment above this line ^^^

never seen so much confusion over a COMMENT:
https://stackoverflow.com/questions/4823468/comments-in-markdown

delgertome commented

Sure. That's easy enough.

A future enhancement could be to only modify the blocks that are recognized in the XML documentation so that manual edits are allowed and it only updates those blocks. For example:

## Summary
This is auto generated, always. All changes will be erased.

## Example
As is this.

## Additional Notes
This was added manually, and therefore will not get erased.

Would be simple enough to parse, but I suppose the question is: what use case does this serve? As I think about it, it almost seems counter productive because it implies that there might be something we WANT documented that isn't documented in the code.

tcartwright commented

Not averse to that idea, but like you I wonder would it serve any real purpose? Would the cost to benefit ratio make it worth it?