1

I am writing detailed information for each function in a class, and hope when others use my python code, they could check the info for each function, by using something like help(function_name)

For example, I have created a python file called text_preprocess.py, in this file I have created a class which includes functions.

class Preprocess():
    def str_process(self, row_string):
        '''
        This Standford CoreNLP package requires the text input as 1 single string.
        The input annotators are in you command line input.
        :param row_string: The string format input for Standford CoreNLP
        :return: Json format output
        '''

        parsed_json = self.nlp.annotate(row_string, properties={
                   'annotators': self.standford_annotators,
                   'outputFormat': 'json'
               })
        return parsed_json

In this function, as you can see the info is within triple quotes. But I don't know how could other users see this info without looking into my code.

I have checked many solutions online, people use help(function_name), but it seems that they wrote the code through terminal, and then type help(function_name), many of those examples do not have class either. Using --help through command line only gives them the parameter descriptions I added through argparse....

So, if I hope others could check the info of my function without looking into the code, where and how could they do that?

Cherry Wu
  • 3,844
  • 9
  • 43
  • 63
  • Try `pydoc` (or `pydoc3`)? – Kevin Mar 25 '17 at 23:18
  • pydoc only works for those built-in python elements, won't work for the functions created by me here – Cherry Wu Mar 25 '17 at 23:42
  • It works just fine for me. Have you tried it? You might also look into [Sphinx](http://www.sphinx-doc.org/en/stable/ext/autodoc.html). – Kevin Mar 25 '17 at 23:51
  • if pydoc works fine for you, could you tell me how did you get the info in my `str_process` function? I tried that, it only tells python built-in elements – Cherry Wu Mar 25 '17 at 23:55

2 Answers2

1
  1. Either be in the same directory as your script, or make sure your script is in one of the directories listed in sys.path (usually, the first option is easier for simple things, but if you want to do the second, use a virtualenv rather than trying to install the module system-wide).
  2. Run pydoc3 text_preprocess to get documentation for the whole module. This recursively includes all of the items below the module, such as classes, their members, and functions.
  3. Run pydoc3 text_preprocess.Preprocess if you just want the class.
  4. Run pydoc3 text_preprocess.Preprocess.str_process if you just want the method.
  5. Use Sphinx if you want nicely-formatted HTML or other formats such as PDF.

You may also want to remove that empty line at the beginning of your docstring; some docstring-parsing code may misinterpret it.

Community
  • 1
  • 1
Kevin
  • 28,963
  • 9
  • 62
  • 81
0

Putting triple quoted strings just below the declaration of a class or method is called documentation. You can read this using Preprocess.str_process.__doc__.

Resin Drake
  • 528
  • 4
  • 9
  • I tried to run this through terminal, under the same folder of my code file text_preprocess.py, but it is showing "Preprocess.str_process.__doc__: command not found". Do you know where should I run this? – Cherry Wu Mar 26 '17 at 03:56
  • @Cherry_Wu This will only work within a Python script. It is not a terminal command explicitly. You have to import the module via Python within the terminal and type this with Python. – Resin Drake Mar 26 '17 at 05:25