riccardoscalco/Pykov

Make a documentation on ReadTheDoc

Naereen opened this issue · 7 comments

Naereen commented

Hi,

First, thanks and 👏 for this small and cool project.
It's neat and well written, I love it!

Second, may I suggest that you write a Sphinx documentation and host it on ReadTheDocs please?
Based on the Markdown documentation that is already available in the README.md file, it could be very easy.

GitHub can be connected to ReadTheDocs to build the site automatically, for instance http://pykov.readthedocs.org/

Thanks in advance; I can't do it for you, but if you need any help, I can assist (I did a few docs on ReadTheDocs already, see this example or this one).

Naereen commented

Using the autodoc Sphinx extension, and apidoc to generate a reStructuredText file, I obtained a documentation directly from the pykov.py file, with no sweat. 😎

It's not 100% complete (based on the docstrings, which are not as complete as what you did in the README.md), but it looks nice:
example_pykov_documentation
(default ReadTheDocs theme)

riccardoscalco commented

Hi, thanks for the suggestion and help.

I used a single readme for the documentation because Pykov APIs are quite few and because I wanted to reduce maintenance effort.

Read the Docs provides a webhook for github, so this weekend I subscribed and did the few steps necessary to build documentation from the README.md file.
According to this docs (https://docs.readthedocs.io/en/latest/builds.html#mkdocs) the existence of a README.md file is sufficient for the creation of a page, but at the moment the page still does not exist, which is weird. Do you have any suggestion?

Naereen commented

Hi,
You are welcome, I will try to help.

I never used Read the Docs with MkDocs.

  • Maybe you can try to write yourself a mkdocs.yml with minimal configuration,
  • Maybe you can ask to build the documentation manually and not wait for a webhook (if you didn't committed anything on GitHub, the webhook has no reason to have been activated). In the build page there is the log file of the building process, you can see if anything fails,
  • You can install MkDocs on your machine, and check that it successively builds a HTML doc from your one file README.md : if it fails, no need to hope for the automated platform to success!
riccardoscalco commented

Thanks for the tips, as first attempt I do a mkdocs.yml and see what happens. I let you know in case of success.

Naereen commented

Hi @riccardoscalco,
Any update?

riccardoscalco commented

Not yet, sorry. I am stuck on the the creation of docs from the README.md file.
Anyway, I think that for such small project a single readme in github is enough.

Naereen commented

Hi,
No problem. As you prefer.