GitHub Action
Pyarch: python package architecture as webpage
The tool to generate dynamic class diagrams of python packages to facilitate their development and maintenance.
Motivation:
- Reduction of the cognitive load when learning the structure of a new package.
- Identification of architecture bottlenecks using static analysis of inter-modular dependencies.
Pyarch can be executed as part of GitHub workflow.
Attribute | Description | Required | Default |
---|---|---|---|
input |
Directory with the package source code | true | |
output |
Directory to save generated HTML file | false | .pyarch/output |
title |
Custom HTML title | false | Python package architecture |
header |
Custom HTML header | false | Python package architecture |
footer |
Custom HTML footer | false | <p style="font-size:15px">Built with ❤️ by <a href="https://www.dkisler.com" target=_blank>Dmitry Kisler - dkisler.com</a></p> |
output
: Path to generated HTML file.
The following GitHub workflow can be used to generate the package architecture diagram and to publish it using GitHub pages.
name: "Pyarch Pages"
on:
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
pyarch-pages:
runs-on: ubuntu-20.04
steps:
# assumption: the workflow is running in the python package repo
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Generate HTML
uses: kislerdm/pyarch@v0.0.2
with:
# Change to the path with the package's source files
input: src
title: "Architecture of my package"
header: "Architecture of my package"
output: public
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
path: 'public'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
Prerequisites:
- python >= 3.8
Steps
- Download the latest release of the python script
- Move it to the bin directory
/usr/local/bin
- Run the script to validate the version:
pyarch --version
Note that sudo permissions will be required. Alternatively, the script can be executed without the step 2
:
python3 pyarch --version
Demo
Note curl is required.
sudo curl -SLo /usr/local/bin/pyarch https://github.com/kislerdm/pyarch/releases/download/v0.0.1/pyarch &&\
pyarch --version
Output:
version: 0.0.1
Prerequisites:
- pylint
- pyarch
Follow the steps to generate the webpage with dynamic architecture diagrams of sklearn:
- Create a clean directory
mkdir sklearn-diagram && cd sklearn-diagram
- Clone sklearn from GitHub to the local repository:
git clone git@github.com:scikit-learn/scikit-learn.git code
- Generate the package architecture diagrams as UML using pyreverse
pyreverse -Akmy -o puml -d . --ignore=test,tests code/sklearn
- Generate the webpage with the dynamic diagrams:
pyarch -i . -o . -v --title="sklearn architecture" --header="sklearn architecture"
The directory is expected to have the following structure:
.
├── code
├── classes.puml
├── packages.puml
└── index.html
Open index.html
using a web-browser:
The project is distributed under the MIT license - feel free to use it as you will.
Please open github issue, and/or PR with a change proposal to collaborate.