pythondocumentation

python "auto" documenting the project


I am aware there is nothing completely to auto documenting, I am just asking about any tool that could help me to make the documentation fast.

I have almost finished my scrapy projects and I want to document the code.

I found sphinx which sounds good, but really it needs hard work to document, plus it just provides a web pages for the projects. I was looking for some tools that could do something like this:

If my code is:

def myfunction(var1, var2):
    return 3 + 3

it should edit the source code and add the needed rst syntax like """.

Then I find sphinx api doc which sounds good, it generates a lot of files, a little bit messy but I can edit them. Nevertheless it didn't add anything about the functions and classes in my code, it just created rst files for each Python script I have. That is not benefial to me because I need for each function the inputs documented and the return documented and a little bit text about the function.

I was expecting that there could be a tool that generates templates for documentation and I update these templates.


Solution

  • What you can do is to get help of modern IDEs.

    For instance, PyCharm has a built-in "Missing docstring" code inspection with an ability to fix it - insert a docstring. For instance, if you have this code:

    def test(a, b):
        return a + b
    

    and if you would inspect it with PyCharm, after applying the "Missing docstring" fix, Pycharm would auto generate a docstring template in a desired format:

    def test(a, b):
        """
    
        :param a: 
        :param b: 
        :return: 
        """
        return a + b
    

    There is more to that - it's quite configurable: