Documentation Fix - Examples and API's being documented diverge considerably

[JohnVonNeumann]

https://hvac.readthedocs.io/en/latest/usage/secrets_engines/kv_v1.html#list-secrets

As you can see here, the api listed, and the example code, are completely different, they are not even remotely close to being the same. Which one should be regarded as the actual source of truth. I can appreciate just running them or viewing the source, but if examples exist, they should probably be correct.

Cheers for your work on HVAC! Love the tool otherwise.

[jeffwecan]

@JohnVonNeumann: I'm not sure I follow. Are you referring to the difference between the source reference links (e.g., hvac.api.secrets_engines.KvV1.list_secrets()) versus the way those methods are called from the hvac.Client class (e.g., hvac.Client.secrets.kv.v1.list_secrets())?

[Lawouach]

Hey,

I was going to create an issue in the same spirit but I feel this one covers it already.

The documentation at https://hvac.readthedocs.io/en/latest/usage/secrets_engines/kv.html says that if you access client.kv.read_secret(path='hvac') it will automatically re-route to the right version but I wonder how that is supposed to work since read_secret is not defined in KV2 anyway.

  File "/tmp/.venv/lib/python3.6/site-packages/hvac/api/secrets_engines/kv.py", line 76, in __getattr__
    return getattr(self._kv_v2, item)
AttributeError: 'KvV2' object has no attribute 'read_secret'

Also, when calling client.kv directly we get a deprecation warning saying we must use client.secrets.kv.

Am I just reading this entirely wrong?

Thanks,

[jeffwecan]

That all sounds right. I'm working through adding doctest to all the existing documentation so I'll make sure to true up that sort of deal as I run across it! 👍

[jeffwecan]

Docs trued up and doctests added for the "overview" examples and all the system backend methods (as well as some basic tests for GCP secrets engine docs). Will consider this issue closed once all auth method and secrets engines docs receive the same treatment....

[Tylerlhess]

I don't know if I'm missing something but the Databases back end is not documented in the current docs.

[drewmullen]

correct: https://github.com/hvac/hvac/issues/453 @Tylerlhess

[mattis-haase]

Also, can we have all the parameters for all classes and methods in the documentation, as well as a complete code example for every method and a complete response example? Similar to boto3. This should be auto generated from code.

[briantist]

Hello! It seems like this issue is describing a lot of different things, and I'm having a little trouble following it.

My inclination is to close this out in favor of more focused issues such as #453 which can be directly addressed.

I'm going to give a little time to see if anyone involved disagrees or has thoughts on that. I will probably close this within a week or two if there's no other responses. Thanks everyone!