switch to sphinx

[graingert]

One thing I was wondering is the https://github.com/jazzband/imaplib2/blob/21ae2ed26d0ca66c683483d1bfdc7c3fb567a048/imaplib2/imaplib2.html file inside the imap2lib package.

Could this be converted to a Sphinx project? Maybe Pandoc allows auto-coverting it to rST or Markdown?

I would really like to have user facing docs on https://imaplib2.readthedocs.io/ so it's clear what the purpose of imaplib2 is. What do you think?

Originally posted by @jezdez in https://github.com/jazzband/imaplib2/issues/13#issuecomment-858425763

[piyueh]

I think we can work on this after releasing v3.6, which is planned to happen once #27 is merged. offlineimap3 has been using imaplib2 v3.6 for a while, but we don't actually have a release version called v3.6.

[matthewhughes934]

Hi,

I'm interested in this project and working on some docs seems like a decent introduction. It was easy enough to convert docs from HTML to RST with pandoc (see https://github.com/matthewhughes934/imaplib2/commit/df4f8aed31fae9f36cf749e765e4ff68bd883a7e, though I haven't carefully read the whole thing yet, so it may have been an imperfect conversion).

It looks like there is some cross over between the HTML docs and some of the pydocs in the code, so I was wondering if it might be worth consolidating those.

[piyueh]

Yeah, consolidating the documentation sounds great! I personally prefer to put the API documentation in Python functions' docstrings and put other documentation (e.g., introduction, installation, example, usage, etc) in the folder doc. I'm not familiar with sphinx, but I suppose it can generate the API documentation from docstrings?

Nevertheless, it's just my personal preference

[graingert]

I'm in favour of whatever gets rid of the debug notice on https://imaplib2.readthedocs.io/en/latest/

If there's any loss in fidelity we can always manually bring it across. Please do make a PR of any kind so we can enable your access to run CI

[matthewhughes934]

personally prefer to put the API documentation in Python functions' docstrings and put other documentation

:+1: yep, that would be my preference too

but I suppose it can generate the API documentation from docstrings?

It can, it's very common across python projects, e.g. CPython uses it for the docs there https://github.com/python/cpython/blob/main/Doc/requirements.txt

[matthewhughes934]

I'm in favour of whatever gets rid of the debug notice on https://imaplib2.readthedocs.io/en/latest/

:laughing: I'm not too familiar with readthedocs, but it looks like if I put some docs under /docs it should do the trick :crossed_fingers:

[piyueh]

PR #30 resolves the issue. Closing it.