Auto-generated online API documentation

[jdpipe]

Exchangelib looks like a nice and comprehensive implementation of the Exchange API in Python. The README.md gives a pretty good sense of the range of options that are provided, but it would be huge help for familiarising oneself with the code if there were also some more extensive class docs generated, eg using Sphinx and Readthedocs.

And while I have your attention, are you aware of any attempts by anyone to use exchangelib to provide a CalDAV interface to EWS calendar data, in a similar way to what Davmail does?

[ecederstrand]

I agree with the need for more formal docs. It's been on my todo since forever :-)

I don't know of anyone using exchangelib to create interfaces like CalDAV.

[ecederstrand]

Useful thread at pdoc3/pdoc#55 (comment)

[ecederstrand]

I've used pdoc3 in the past and like it for its simplicity.

If we use that, we need to change the params and return value documentation in docstrings, since pdoc doesn't support the ReST-style that we (actually, pycharm) defaults to. Here's an example of a format supported by pdoc: http://google.github.io/styleguide/pyguide.html#383-functions-and-methods

[spotlesstofu]

Hi! I recently discovered this project (thanks for sharing) and I'd really like this issue to be solved.
I opened a pull request, please let me know what you think!

[ecederstrand]

I merged your changes. Thanks!

Now we need to generate the HTML documentation and make it available somewhere.

[spotlesstofu]

Thank you! I'm glad you appreciated my work.
A way to publish the HTML is to use Github Pages.

If you run

pdoc3 --html exchangelib -o docs

all the HTML will be in the docs folder. Then you go in repo settings and enable Github Pages. Quite easy.

Every time the docstrings change, HTML must be re-generated. Maybe it can be done automatically with git hooks.

pdoc3 --html exchangelib -o docs --force

How does this sound?

[ecederstrand]

Thanks for the explanation. There's now a link to the generated documentation at https://ecederstrand.github.io/exchangelib/

[ecederstrand]

I moved most of the README to the docs site, added a ToC and made some CSS adjustments to the docs site. Closing, but feel free to suggest further improvements :-)