I found "Unknown option" message uninformative

Thanks for docsig project. Our project has been using it for years, even if I'm new to docsig myself.

I ran into the message unknown option to disable 'E113'. It did include a directive to disable that option. I figured I'd try to chase down what E113 used to be, but was unable to do so. I was unable to track down what happened to the "E"-prefixed error codes. I think they changed to start with "SIG", but I there was no "SIG113".

What did E113 used to mean? How do I translate that into the current error codes? Is there documentation I'm missing on retired error codes?

Hoping this issue will help the People of the Future find this information.

Hi @plocket

Thanks for opening the issue, and the support

I apologies for the confusion

TL;DR E113 is now SIG101

What I could have done better is ensure there were multiple versions available with readthedocs

Here's the documentation https://github.com/jshwi/docsig/blob/4d22be2863b595c363d4757ee933e11d9f0c62d4/docs/deprecated/messages.md

---

In order for you to continue using this and receiving updates, yeah I recommend you continue using this with https://github.com/jshwi/docsig/releases/tag/v0.69.0 onwards. Prior to that version the E prefix errors work alongside their corresponding SIG messages. Although, the order was changed, so it wasn't just the prefix, but the code as well.

The deprecation was live for over half a year, and eventually the old style messages were removed. There was also documentation to assist in the migration. Ideally it would have been as noticeable as possible. There was a warning linking the user to the documentation if the E prefix was used, like the following

$ docsig --version
# 0.68.0
$ docsig . -d E101
# /Users/swhitlock/.pyenv/versions/3.8.13/bin/docsig:8: DeprecationWarning: Exxx errors are deprecated and might not be supported in a future version, see https://docsig.readthedocs.io/en/latest/deprecated/messages.html
#  sys.exit(main())

Since the support for that format was removed, so was the documentation

I hope this helps

I also welcome any recommendations you may have for me as to how this could have been easier for you, and anything I could do better in the future if a change similar to this was ever made again i.e. kept the documentation up longer, and prior versions of the docs available. I think you suggested that the error could have been better, so I'll take that on board, I could implement a more informative error - I think I should have done that to make the transition easier

Cheers! Stephen

Oh I forgot to add, this might have helped also (the short/symbolic messages remain the same - I don't recall changing any)

$ docsig --list
# SIG001: unknown module comment directive '{directive}' (unknown-module-directive)
# SIG002: unknown inline comment directive '{directive}' (unknown-inline-directive)
# SIG003: unknown module comment option for {directive} '{option}' (unknown-module-directive-option)
# SIG004: unknown inline comment option for {directive} '{option}' (unknown-inline-directive-option)
# SIG005: both mutually exclusive class options configured (mutually-exclusive-options)
# SIG101: function is missing a docstring (function-doc-missing)
# SIG102: class is missing a docstring (class-doc-missing)
# SIG201: duplicate parameters found (duplicate-params-found)
# SIG202: includes parameters that do not exist (params-do-not-exist)
# SIG203: parameters missing (params-missing)
# SIG301: description missing from parameter (description-missing)
# SIG302: syntax error in description (syntax-error-in-description)
# SIG303: parameter appears to be incorrectly documented (param-incorrectly-documented)
# SIG304: bad token used to close parameter declaration '{token}' (bad-closing-token)
# SIG401: param not indented correctly (incorrect-indent)
# SIG402: parameters out of order (params-out-of-order)
# SIG403: spelling error found in documented parameter (spelling-error)
# SIG404: documented parameter not equal to its respective argument (param-not-equal-to-arg)
# SIG501: cannot determine whether a return statement should exist (confirm-return-needed)
# SIG502: return statement documented for None (return-documented-for-none)
# SIG503: return missing from docstring (return-missing)
# SIG504: return statement documented for class (class-return-documented)
# SIG505: return statement documented for property (return-documented-for-property)
# SIG506: description missing from return (return-description-missing)
# SIG901: parsing python code failed (invalid-syntax)
# SIG902: failed to read file (unicode-decode-error)

Stephen

Thank you for the thorough reply. From my own experiences, I realize documentation is a huge task and deprecating old behavior is especially tricky. As for how to improve, maybe issues like this one can be enough. They might help future users discover answers that are otherwise hard to find. It's still work, but I hope it can be less work than other solutions.

If you find this work exciting, versioning the documentation could be a good alternative. The Docusaurus documentation framework gives a user the ability to version documentation, but they also have a warning:

Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!

I can see you already do a lot of work here and I don't want to add to it.

hey @plocket sorry for the delay in responding, you're right - busy busy very interesting, I look forward to having a look when I get a moment I'll get back to you soon! Cheers!

Hey @plocket

The Docusaurus documentation framework gives a user the ability to version documentation looks really cool. I like nifty tools like this and I had fun playing around

The part you mentioned, plus the below is what makes me think it wouldn't be a suitable option for this package

Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.

By the looks of it this creates extra versions to revisit or revert that are available in all git commits, and it's easier to view changes in the filesystem. I see the need for things like database migrations, where the database exists separately from a codebase and the build is locked in to be used later if need be. And I see the use in docs where they also exist separately from the code. The docs here have a more like for like relationship with the code. The docs aren't that big on their own, and most pages are generated from docs and code in the repo. Also, apart from this breaking change and new features I don't see the docs changing that often

In this instance we can just revisit old versions on https://docsig.readthedocs.ioI decided i prefer #590 and changes to docs are always available with git blame

Now it's possible to view these messages here https://docsig.readthedocs.io/en/v0.55.0/usage/messages.html

I hope your suggestion didn't fly over my head and the decision I made was educated enough. Again, I appreciate your feedback and input. It helped me a lot in regards to how things can be improved. I hope the availability of old versions on https://docsig.readthedocs.io/ has improved docsig

Cheers, Stephen