Package: pycodedoc
pycodedocWelcome to pycodedoc, a Python tool leveraging generative AI to effortlessly document your Python projects.pycodedocFeatures📚 AI-Generated Documentation💻 CLI tool🐍 Python API🛠️ InstallationPypiDevelopmentGraphvizOpenAI key💻 CLI Usage📁 Base directory💲 Cost of running the tool🤖 Selecting a specific model🔖 Configuring prompts📂 Output directory💾 Using code structure🔽 Reducing the documentation process🐍 API UsageGenerating full documentationGenerating part of the documentationFeatures📚 AI-Generated DocumentationUses LLMs to automatically generate markdown documentation containing:an overview of the project as a whole, its main functionalities and its structuredescriptions of the modules used in your project and how they interact with each otherdescriptions of the classes used throughout your projectgraphs showing the execution flow of your code💻 CLI toolThe CLI tool allows you to easily:modify the prompts you want to use for documenting your projectuse the OpenAI model of your choiceestimate the costs of generating the documentation beforehand🐍 Python APIThe library's API enables you to build on top of the tool🛠️ InstallationPypipipinstallpycodedocDevelopmentAlternatively to Pypi, you can clone the repository and install the package in editable mode :gitclonehttps://github.com/DivergerThinking/pycodedoc.gitcdpycodedoc
pipinstall-e.GraphvizTo generate graphs showing the execution flows of your code we are using thecode2flowpython library which requires having graphviz. You can follow their documentation for installing the library on your corresponding OS:https://graphviz.org/download/, even though another very simple OS-free way of doing is to install it using conda:condainstallgraphvizIf you don't want to visualize your code's execution flow, you can ignore this step.OpenAI keyCurrently, the tool only supports OpenAI as a provider. To add your OpenAI key, export it as an environment variable via the terminal:exportOPENAI_API_KEY="..."💻 CLI UsageOptionsDescription--base-diror-dThe directory of the Python project you want to document.--output-diror-oThe output directory path where the documentation is written. Default is "docs/".--modelor-mThe OpenAI model to use for generating the documentation. Default is "gpt-3.5-turbo-0125".--estimateor-ePrints estimation cost of generating the documentation. Default is False.--configureor-cWrites the defaults prompts to a prompt.toml file which can be modified. Default is False.--use-structureor-usUse the structure of the code to generate the documentation. Default is False.--no-relationsor-nrDoes not generate relationship between modules. Default is to generate them.--no-classesor-ncDoes not generate classes descriptions. Default is to generate them.📁 Base directoryTo run the tool you must specify the directory where your python project is found using the--base-diror-doption. Ideally, all of your modules are stored in a single directory (ex. src/ directory). Here is an example on document thepycodedocproject itself.pycodedoc-dsrc/pycodedocThis will write the output to a markdown file under "./docs/project-doc.md".NOTE: Only Python files are used for documenting the project.💲 Cost of running the toolThe cost of running the tool largely varies based on the size of the codebase and the model you use. To avoid bad surprises, you can first estimate the cost of running the tool by using the--estimateoption:pycodedoc-dsrc/pycodedoc--estimateRunning the tool on the ./src/pycodedoc/ directory approximately costs $0.01 if using the default configuration.🤖 Selecting a specific modelBy default, the tool uses the latestgpt-3.5-turbo-0125model since it is currently the cheapest capable chat model from OpenAI.
You can however use another model by passing the model parameter using the--modelor-moptionpycodedoc-dsrc/pycodedoc-mgpt-4-0125-preview🔖 Configuring promptsThe prompts used for documenting your codebase can be accessed and modified by using the--configureor-coption.pycodedoc--configure📂 Output directoryBy default, the documentation is stored under the /docs directory. If this directory is already in use and you want to avoid using it, you can modify the output directory with the--output-diror-ooptionpycodedoc-dsrc/pycodedoc--oproject_docs💾 Using code structureInstead of using the entire modules' content, you can only use the structure of the code (imports, signatures and function descriptions) via the--use-structureoption. This is particularly useful if you have large files whose content may exceed the model's context window maximum token limit.pycodedoc-dsrc/pycodedoc--use-structureNOTE: the descriptions for each function in the files will be generated beforehand to make the code structure more meaningful while keeping the file's token count low. The cost of this process is (more or less) offset by the reduction in tokens from the resulting code structure.🔽 Reducing the documentation processYou can also reduce the documentation process by NOT generating descriptions for the classes or modules' relationships using the--no-classesand--no-relationsoptions.pycodedoc-dsrc/pycodedoc--no-classes--no-relationsThis reduces the overall context passed to the LLMs, reducing costs and speeding up the generation process.🐍 API UsageYou can build on top of the tool by using the main functions from the API.Generating full documentationThe below code is the equivalent of runningpycodedoc-d src/pycodedoc` using the CLI:frompycodedocimportDocGen# to modify the prompts used, you can pass a dict reflecting the prompts.toml file to the `prompts=` argumentdocgen=DocGen(base_dir="src/pycodedoc")# other configurations are the same as in the CLIdocgen.generate_documentation()Generating part of the documentationThegenerate_descriptionsfrompycodedocimportDocGen# to modify the prompts used, you can pass a dict reflecting the prompts.toml file to the `prompts=` argumentdocgen=DocGen(base_dir="src/pycodedoc")# other configurations are the same as in the CLIdocgen.generate_descriptions("functions")# OUTPUT -> list of descriptions for each function in the projectdocgen.generate_descriptions("functions",module_path="parser.py")# OUTPUT -> list of descriptions for the functions inside the parser.py moduledocgen.generate_descriptions("classes")# OUTPUT -> list of descriptions for each classes in the projectdocgen.generate_descriptions("classes",module_path="parser.py")# OUTPUT -> list of descriptions for the classes inside the parser.py moduledocgen.generate_descriptions("modules")# OUTPUT -> list of descriptions for each modules in the projectdocgen.generate_descriptions("modules_relations")# OUTPUT -> list of descriptions for each classes in the projectdocgen.generate_descriptions("project")# OUTPUT -> project description [str]. NOTE: first you need to generate the modules descriptions