How do I go from .py to .html or some other nicely laid out documentation?

Answered
Avatar
Permanently deleted user
Created

Wanted: documentation auto-generated from .py files.  I want to run something magical inside PyCharm on a python file and get a page that displays only the """ """ strings and the classes in an organized way.  I guess I am not understanding a major part of how documentation works.  

My hope was that it would be easy to show my students that there is some benefit to documenting code and that it's kind of cool. They are 15 years old and documentation tastes like cod liver oil.

Outside PyCharm, I can take a .py file and get a .html file on the command line, for example like this:  pydoc -w ./docTest.py. I know that this is completely unrelated to PyCharm.  My students would benefit from it being even easier, and done inside PyCharm.

Can a documentation display be done inside PyCharm?  Is there a straight forward way to achieve this goal without having to know much about rst, docutils, and Sphinx? 

Don't get me wrong. I very much appreciate the help I get in writing the documentation with param and returns etc. The editing part is great, and so is the pop up documentation.

I do understand that PyCharm can run on .rst files and have even done so with docutils inside PyCharm. But how to make them from Python .py eludes me. So, I ask for help after I have perused pages and pages of technical information about docutils and Sphinx and PyCharm itself.

I have PyCharm CE 2016.2.1 (PyCharm Community Edition) and I'm using python 2.7.12 (but also use 3.5.2).  I have Sphinx 1.5.1 and docutils 0.13.1. I use El Capitan, but students have various versions of MacOS and Windows and Ubuntu.

Thank you very much!

Votes

1

Share

4 comments
Avatar
martin borus
Created

Same problem here - to make it more simple:

I know how to create Sphinx documentation from a folder named "sphinx" full of rst-files and other things like screenshots.

I have a different folder "src" which has a lot of ".py" files.

I'm looking for a simple example how to setup PyCharm (Professional 2016.3 or better) to extract documentation from a source file, so that I do not need to manually write a ".rst" file to document certain ".py" files.

Any tutorial? A simple example to add one ".py" file might be all that's needed to understand how this is supposed to work...

-----

So far I learned to change the "conf.py" file in the sphinx directory to include the path to the source code.
When I uncomment/add the lines, on document generation the printed path includes the source path

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.join(os.path.abspath('..'),'src'))
print(sys.path)


 

I now placed a dummy.py file with this content in the path

 


def helloworld():

    """

    A helloworld function

    :return: Nothing
    """

    pass


 

The index.rst file in the sphinx directory should now import the comment.

.. documentation master file, created by
   sphinx-quickstart on Tue Sep 27 18:19:08 2016.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. automodule::dummy
  .. autofunction:: helloworld()
 
Hello World
-----------

Running this creates the document, gives no error message, but does not import any comments.

Any help?

 

1
Avatar
martin borus
Created

Some progress:

the "conf.py" file needs to activate the autodoc plugin

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc']

Once that's added, add this to your index.rst

.. autofunction:: dummy.helloworld

and re-run Sphinx from PyCharm.

The function appears!

Once that runs, you can now visit the examples at

https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example

and learn more.

1
Avatar
Mikhail Golubev
Created

Hi there,

 

Unfortunately, there is no built-in action to generate such documentation from docstrings found in the project sources. The right way to do it at the moment is to setup Sphinx with "autodoc" plugin, as Martin suggested (perhaps, with the help of "sphinx-apidoc" script), and then use special kind of run configuration (Python docs | Sphinx task) to launch a Sphinx task, e.g. "html", when you need to re-generate it. You can then share this run configuration together with your project sources among the students. 

Alternatively, you can write a script that does all of that and create a dedicated external tool to easily run it in PyCharm.

0
Avatar
Permanently deleted user
Created

Thank you for your replies and clear suggestions.

0

Please sign in to leave a comment.