![[Formales]] ![[module_pydoc__740859525.png]] [pydoc: Documentation generator and online help system](https://docs.python.org/3/library/pydoc.html)<br> In: *Pydoc Documentation* > [!TLDR] What is Pydoc? > Pydoc is a module in Python that generates Python documentation in both HTML and text formats. It can produce documentation for Python modules, classes, functions, and methods from their source code. > Pydoc can be used as a command-line tool and within your Python code. # Pydoc Overview ## Command-Line Usage > [!multi-column] > >> [!NOTE] Starting the Pydoc Server >> Run `python -m pydoc -p 1234` to start a Pydoc server on port 1234. Replace `1234` with your preferred port number. > >> [!NOTE] Viewing Documentation >> To view documentation for a specific module, class, or function, use `python -m pydoc <name>`. Replace `<name>` with the name of the module, class, or function. > [!NOTE] Generating HTML Documentation > To generate HTML documentation for a module, use `python -m pydoc -w <name>`. This will create an HTML file named `<name>.html`. ## Using Pydoc in Code > [!multi-column] > >> [!NOTE] Importing Pydoc >> First, you need to import Pydoc into your Python script: `import pydoc`. > >> [!NOTE] Getting Help >> Use `pydoc.help(<object>)` to get help on a Python object. > [!NOTE] Generating Text Documentation > `pydoc.render_doc(<object>)` can be used to generate a text documentation string for a given object. ## Advanced Pydoc Features > [!multi-column] > >> [!NOTE] Searching Documentation >> Use `python -m pydoc -k <keyword>` to search for a keyword in all available modules' documentation. > >> [!NOTE] Browsing Documentation in GUI >> Run `python -m pydoc -g` to start Pydoc with a graphical interface for easier browsing. ## Tips for Effective Documentation > [!multi-column] > >> [!NOTE] Writing Docstrings >> Always write comprehensive docstrings for your functions, classes, and modules. Pydoc uses these docstrings to generate documentation. > >> [!NOTE] Docstring Formats >> Use consistent formatting in your docstrings. While Pydoc does not enforce a specific style, it is good practice to pick a style (such as reStructuredText or Google style) and stick with it. ## Example ```python def add(a, b): """ Add two numbers together. Parameters: a (int or float): The first number. b (int or float): The second number. Returns: int or float: The sum of `a` and `b`. """ return a + b ``` # Utilize Pydoc ![[utilize_pydoc__736642762.png]] To utilize `pydoc` effectively with the example provided in the cheat sheet, let's walk through how you can generate documentation for the given `add` function using both command-line and programmatic approaches with `pydoc`. ## Using Pydoc from the Command Line > math_functions.py ```python def add(a, b): """ Add two numbers together. Parameters: a (int or float): The first number. b (int or float): The second number. Returns: int or float: The sum of `a` and `b`. """ return a + b ``` ### View Documentation Open your command line or terminal, and navigate to the directory containing `math_functions.py`. To view the documentation for this module, execute (bash): ```bash python -m pydoc math_functions ``` ### Generate HTML Documentation To generate an HTML version of the documentation that you can view in a web browser, run (bash): ```bash python -m pydoc -w math_functions ``` This will create a file named `math_functions.html` in the same directory, which contains the documentation for your module. ## Using Pydoc Programmatically You can also access documentation from within Python code. This can be particularly useful for interactive exploration. ### Import Pydoc Start by importing `pydoc` in your Python session or script. ```python import pydoc ``` ### View Documentation in Python Use `pydoc` to view the documentation for the `add` function. This can be done using `pydoc.render_doc` or `pydoc.help`. ```python # For a string representation doc_string = pydoc.render_doc('math_functions.add') print(doc_string) # Or to view help directly pydoc.help('math_functions.add') ``` # Port Usage - Why? ![[port_usage_why__739852188.png]] Using a port with `pydoc` serves a specific purpose: it allows you to start a local web server that hosts the generated Python documentation, making it accessible through a web browser on your local machine. This setup is convenient for browsing documentation offline or for working in a development environment that lacks internet access. Let's delve into the reasons for using a port and the considerations for choosing one. ## Why Use a Port for Pydoc? > [!multi-column] > >> [!NOTE] Accessibility >> Running `pydoc` on a specific port allows you to access the documentation through your web browser by navigating to `http://localhost:<port>`, where `<port>` is the port number you specified. > >> [!NOTE] Isolation >> By choosing a specific port, you ensure that the `pydoc` service doesn't conflict with other services running on your machine that might be using other ports. > [!NOTE] Control > It gives you control over where and how the documentation is accessed, especially useful in environments with specific network configurations or security requirements. ### Choosing a Port When choosing a port number, there are a few considerations to keep in mind: > [!multi-column] > >> [!NOTE] Well-Known Ports >> The range from 0 to 1023 is reserved for well-known ports used by system services and common applications. It's best to avoid these to prevent conflicts. > >> [!NOTE] Registered Ports >> The range from 1024 to 49151 is known as the registered ports range, used by many applications. While it's less likely to cause conflicts than well-known ports, some of these ports are still commonly used. > [!NOTE] Dynamic/Private Ports > The range from 49152 to 65535 is designated for dynamic or private use and is less likely to conflict with other services. This range is often a safe choice for development purposes. ### Recommendations > [!multi-column] > >> [!NOTE] Use Dynamic/Private Ports >> For running `pydoc`, it's generally safe to use ports within the dynamic range (49152-65535). These ports are less likely to be used by other applications or system processes. > >> [!NOTE] Check for Port Availability >> Before starting `pydoc` on a chosen port, ensure that the port is not already in use. You can do this using tools like `netstat` or `lsof` on Unix-like systems, or by simply trying to start the server and seeing if you encounter an error indicating the port is already in use. To start a `pydoc` server on port 55555 (assuming it's free), you would use the command (bash): ```bash python -m pydoc -p 55555 ``` This would allow you to access the documentation by navigating to `http://localhost:55555` in your web browser. # Three Advanced Examples ![[three_advanced_examples__740773577.png]] Below are three examples that cover different aspects of `pydoc,` including command-line usage, generating documentation programmatically, and integrating documentation practices into development workflows. ## Creating a Documentation Web Server for Your Project (bash) You're working on a Python project with multiple modules, and you want to make it easy for your team to access the entire project's documentation in one place. ```bash python -m pydoc -p 8080 ``` This command starts a `pydoc` web server on port 8080. When run from the root of your project directory, it serves documentation for all Python modules and packages found in the directory. Team members can navigate to `http://localhost:8080` in their web browsers to access the documentation. This is particularly useful in a development environment where you want to quickly access documentation for different parts of your project without generating HTML files manually. ## Programmatically Generating Documentation for Dynamic Inspection (python) You're developing a tool that inspects Python code and you want to include a feature that generates documentation for identified modules, classes, or functions dynamically. ```python import pydoc def generate_documentation(object_name): try: obj = __import__(object_name) doc = pydoc.render_doc(obj) return doc except ImportError: return f"No documentation found for {object_name}" # Example: Generate documentation for the 'json' module print(generate_documentation('json')) ``` This Python function, `generate_documentation`, dynamically imports a module by name and uses `pydoc.render_doc` to generate its documentation. This can be integrated into larger applications for dynamic code analysis or documentation generation. This approach is valuable for tools that need to inspect code and present documentation to the user based on their interactions or the objects they are working with. ## Generating and Storing HTML Documentation as Part of Your CI/CD Pipeline (yaml) You want to ensure that up-to-date HTML documentation is generated for your Python package every time changes are pushed to your repository and stored in a specific directory or even served from your project's website. ```yaml - name: Generate HTML documentation run: | mkdir -p docs/html python -m pydoc -w my_package mv my_package.html docs/html/ ``` This example represents a step you might add to a GitHub Actions workflow (or a similar CI/CD tool). It creates a directory for HTML documentation (if it doesn't already exist), uses `pydoc` to generate HTML documentation for `my_package`, and then moves the generated HTML file to the specified documentation directory. This automated step ensures that documentation is always up to date with the latest codebase and can be particularly useful for projects that want to host their documentation on a website or an intranet.