¿Cómo generar una documentación usando Python?

La documentación mejora la legibilidad del código. Hay muchas herramientas que nos ayudan a crear documentaciones. Una de esas herramientas es pdoc para escribir documentación para proyectos de python. 

Instalación: Ejecute el siguiente comando pip en la terminal.

pip3 install pdoc3

Ahora navegue (a través de la línea de comando) a la carpeta donde se guarda nuestro programa Python. Digamos que el nombre de nuestro programa es Numbers.py. Es una clase sencilla que tiene 2 funciones, una para encontrar el factorial del número y otra para comprobar si el número es primo o no.

class Numbers :
   
        """
        This class will be used to perform operations on numbers.
        To find out their factorial, check whether the number is prime
        """
   
        def isPrime(self, number) :
   
                '''
                A method to check whether a number is prime
                '''
   
                i = 2
                while(i <= number / 2) :
                        if number % i == 0:
                                return False
                        i += 1
                return True
          
        def factorial(self, number) :
              
                """
                A function that finds out the factorial of numbers
                """
                result = 1
                while(number >= 2) :
                        result *= number
                        number -= 1
                return result

Adición de strings de documentación en clases y métodos. Los docstrings son una parte importante de la documentación. 

Después de navegar a la carpeta (a través de la línea de comando) donde se guarda nuestro código (Numbers.py). Tenemos que escribir este comando en la terminal:

 pdoc --html Numbers.py

Estructura de directorios

Después de ejecutar el comando –html que se muestra arriba, se creará una carpeta HTML en el directorio donde se guarda Numbers.py. Dentro de esa carpeta HTML, se creará un archivo llamado Numbers.html. Navegue a la carpeta HTML y abra Numbers.html.

Números.html

Numbers.html debería verse así. Acabamos de crear la documentación adecuada de nuestros Números de clase. En la columna izquierda (Índice) de Number.html, se ven las clases y sus métodos. Recuerde las strings de documentación que escribimos, están disponibles debajo de sus respectivas clases y métodos.