search

apache / libcloud

Apache Libcloud is a Python library which hides differences between different cloud provider APIs and allows you to manage different cloud resources through a unified and easy to use API.
https://libcloud.apache.org
Apache License 2.0
2.04k stars 925 forks source link

Fix syntax issues in docstrings in the code #1936

Open Kami opened 1 year ago

Kami commented 1 year ago

When generating API documentation for various drivers using sphinx, tons and tons of warnings are printed due to an invalid docstring syntax in many places.

Those syntax issues should be fixed and once all the issues are fixed, sphinx and RTD config should be update to fail on warning. This way we will detect such issues early as part of CI.

Keep in mind that those fixes mostly can't be automated and it will be manual laborious and time intensive task.

Kami commented 1 year ago

The biggest offender by far (hundreds of errors) is the Outscale compute driver.

To make this task more manageable, I think it makes a lot of sense to simply exclude Outscale driver from the API docs generation and focus on fixing syntax issues everywhere else to begin with.