Giters

athackst / mkdocs-simple-plugin

Build documentation files inside your code into a MkDocs site.

Home Page:https://althack.dev/mkdocs-simple-plugin

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Divergence between docs and commands for testing changes to plugin code

gwhitney opened this issue · comments

commented

The "Developing" documentation page, currently generated from mkdocs_simple_plugin/README.md, specifies the test commands tests/integration/test.bats and tests/test_flake8.sh but the actual tests are tests/test.bats and tests/test_lint.sh, respectively.

I would be happy to submit a pull request to align. However, my recommendation would be to move the Developing markdown, or at least the testing portion of it, to .github/workflows/test.yml where the testing is actually performed, and ideally ensure the extraction is such that the actual code lines that perform the tests are the ones that end up in the documentation page, to make certain that through any future development that the documentation and reality coincide. (From my point of view, that guarantee of correspondence is one of the key added values of a documentation scheme like that of simple.)

Please advise how you'd like things to proceed here.

commented

As a developer are you more likely to check the website or look at the docs in the code?

I'd lean more toward the docs in the code, and wouldn't think about looking in .github/workflows for how to run things.

How about just updating for now? Probably something like linking to/including the files would at least throw-up errors in CI that would force it to be up to date would be the better answer here.

commented

Absolutely more likely to check the website. I love documentation. That's why I am here contributing to your project!

If the principle is that documentation should be near the documented code, then it would seem to imply the documentation for testing should be with the code that does the testing, which is .github/workflows/test.yml

Or, if for other reasons, it's best to keep the docs where they are (say because they cover other aspects in addition to testing), then in the semiliterate extension, I would take care of this by just grabbing the code lines from .github/workflows/test.yml into mkdocs_simple_plugin/README.md -- you've said that stuff like that from the point of view of the simple plugin should just be done with macros instead. Can you provide any guidance on how one might grab those testing lines from test.yml and interpolate them into the plugin README with macros? Would be happy to do that, if I had a basic idea of how.

It just seems a shame to patch a divergence like this in a way in which the divergence could happen again just as easily...