setup a documentation website auto-generated from code docstrings

[wyli]

Additional comment from #21

We should also nail down what format comments should be in, I would suggest Numpy format https://numpydoc.readthedocs.io/en/latest/format.html as a good hybrid of Google docstrings and reStructured Text formats, however Pytorch uses Google docstrings so maybe we should stick to that.

[atbenmurray]

Copying in the initial email for complete issue history; hope that's ok.
Hi Ben,
This item was assigned to you and me. If you don’t mind, I can start and put together a proposal based on what we did before.

Let me know if this is okay with you.

Thanks,
Yan

[atbenmurray]

I don't have experience with python doc generation; do you have some go to tools for it?

[vfdev-5]

If I could put my 2 cents to this issue. In PyTorch, Torchvision (and Ignite) they are using Sphinx for docs generation. For example, for torchvision:

• https://github.com/pytorch/vision/tree/master/docs
• Makefile can be left as is (replacing the project name) and conf.py should be adapted to your project.
• main page is https://github.com/pytorch/vision/blob/master/docs/source/index.rst
• make html builds the documentation

Documentation pages are written in reStructured Text formats. Docstrings are as mentioned in the first message are in Google style.

HTH

[yanchengnv]

Yes we do. We have been doing that in Clara Train

…

Sent from my iPhone On Jan 14, 2020, at 11:59 AM, Ben Murray <[email protected]<mailto:[email protected]>> wrote: I don't have experience with python doc generation; do you have some go to tools for it? — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub<#12?email_source=notifications&email_token=AN367GI3D7B4H3X3BI3RTRLQ5XTDTA5CNFSM4KFKGES2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEI5JBHY#issuecomment-574263455>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AN367GKHE4GSIM37WEHOBULQ5XTDTANCNFSM4KFKGESQ>.

----------------------------------------------------------------------------------- This email message is for the sole use of the intended recipient(s) and may contain confidential information. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message. -----------------------------------------------------------------------------------

[yanchengnv]

We also use Sphinx in Clara Train

…

Sent from my iPhone On Jan 14, 2020, at 7:12 PM, vfdev <[email protected]<mailto:[email protected]>> wrote: If I could put my 2 cents in this issue. In PyTorch, Torchvision (and Ignite) they are using Sphinx<https://www.sphinx-doc.org/en/master/usage/quickstart.html> for docs generation. For example, for torchvision: * https://github.com/pytorch/vision/tree/master/docs * Makefile can be left as is (replacing the project name) and conf.py<https://github.com/pytorch/vision/blob/master/docs/source/conf.py> should be adapted to your project. * main page is https://github.com/pytorch/vision/blob/master/docs/source/index.rst * make html build the documentation Documentation pages are written in reStructured Text formats. Docstrings are as mentioned in the first message are in Google style. HTH — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub<#12?email_source=notifications&email_token=AN367GL5NKU3AX6FB6AL5RTQ5ZIGPA5CNFSM4KFKGES2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEI6S3VY#issuecomment-574434775>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AN367GOWVX5X4QDGA3HSIWTQ5ZIGPANCNFSM4KFKGESQ>.

----------------------------------------------------------------------------------- This email message is for the sole use of the intended recipient(s) and may contain confidential information. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message. -----------------------------------------------------------------------------------

[IsaacYangSLA]

I forked this repo and created the document of MONAI API here. It was built by Sphinix, and github.io automatically pulls master branch /docs folder into repository's github pages. I tried to avoid pollute this repo, so once that page looks OK, I will create a PR.

There are at least three sub-tasks in this tasks.

1. Creating source RST files. Usually, they are tutorials, examples, and user guides.
2. Running sphinx's document build process to generate API document from docstring, and build html files from the combination of API document and RST files.
3. Publishing the html files to some document website (github.io, currently).

For current stage, we are doing most of them manually. In the future, we would like to automate them as part of CD.

[pdogra89]

Isaac to investigate Readthedocs service.

[IsaacYangSLA]

ReadTheDocs limits memory to 1GB. However, pytorch package is around 800MB, which exceeds the memory size. With some mocked packages, I managed to build all pages and pushed them to https://monai-readthedocstest.readthedocs.io/en/latest/. The process required manually creating mocked packages/classes/functions, and did not scale well. Please take a look at https://gitlab.com/project-monai/readthedocstest/-/tree/master for those mocked codes.

[vfdev-5]

@IsaacYangSLA maybe it is possible to use pytorch CPU only to build the docs which takes < 100mb

[wyli]

fixed via #68.