001 - Simple App for Sphinx Documentation#

Overview#

This document provides prompts for creating a simple app that integrates with Sphinx documentation to visualize Graphviz DOT diagrams. The app will automate the conversion of DOT files to SVG format and generate corresponding Sphinx documentation.

Story behind following prompts#

One day I needed to document a project that involved complex Graphviz DOT diagrams. I wanted to visualize these diagrams in Sphinx documentation. I decided to automate the workflow using a combination of Makefile, shell scripts, and Sphinx-doc. The goal was to create a seamless experience where adding or removing DOT files would automatically update the SVGs and documentation.

Of course I used GitHub Copilot to help me with the code snippets. Once final project did work I created a set of prompts to help others replicate the process easily.

Prompts#

Field

Value

Date

2025/06

Version

0.1.0

Tested with

`GitHub Copilot`_

Model

GPT-4.1

Prompt 1: Initial Project Setup#

Prompt:

Please scaffold a project for documenting and visualizing Graphviz DOT diagrams with Sphinx.

The project should include:

  • A Makefile that automates DOT -> SVG conversion and Sphinx documentation build.

  • Sphinx documentation with a modern theme (suggest one).

  • Shell scripts for generating SVGs and RST files dynamically from DOT files.

  • A sample README.md with usage instructions.

  • Place DOT and SVG files in a suitable subfolder (e.g., _images).

  • Ensure the workflow is automated: adding/removing DOT files updates SVGs and documentation.

  • Add a .gitignore for build and generated files.

  • Make it cross-platform if possible, but Linux/WSL/Bash is fine as default.

Prompt 2: Create README.md for Python Environment#

Prompt:

Please generate a concise README.md section for Python environment setup using uv tool.

  • Include commands for creating a virtual environment, installing dependencies from requirements.txt, and freezing/updating requirements.

  • Mention that the automation scripts are Bash-based and recommend WSL or Git Bash for Windows users.

Prompt 3: Final Workspace Review#

Prompt:

Please review my current project workspace for a Sphinx-based documentation and diagram automation project.

  • List any missing or redundant files.

  • Suggest improvements for automation, file organization, and cross-platform compatibility.

  • Check if all scripts are referenced in the Makefile and if static assets are in the correct place.

  • Recommend .gitignore entries and any README improvements.

  • Summarize your findings in a table.

References#