Code visualization for the praw codebase

[ivanmilevtues]

Code visualization for the praw codebase

This change contains high-level diagram documentation which is aimed at helping new people get up-to-speed with the existing codebase. You can see how they will look in the github ui here:
https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/praw/on_boarding.md

Feature Summary and Justification

This pull requests contains all the docs for a new person to get a high-level understanding of the praw project before they dive deep into a module/component which is interesting to them.

Me and a friend leverage static analysis and LLMs to generated those, we believe that visuals are the best way to get started on a new project. Further in order to keep them always up-to-date we are currenlty working on a github action!

I would love to hear what do you think about the above said, any feedback is more than welcome!

Full disclosure: we're trying to turn this into a startup, but we're still in a very early stage and figuring out what will actually be useful for people.

References

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

Remove the Stale label or comment or this will be closed in 30 days.

[ivanmilevtues]

A quick update to this stale PR :D.
The generation logic is now open-source: https://github.com/CodeBoarding/CodeBoarding so you can take a look if interested!

[LilSpazJoekp]

This looks cool! Is there a way to automatically update it via GitHub actions?

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

Remove the Stale label or comment or this will be closed in 30 days.

[ivanmilevtues]

@LilSpazJoekp Yes, we do have an action to keep the up-to-date. I'd be more than happy to add it to the inegration here :)

[LilSpazJoekp]

Awesome! Would you mind adding that to the PR?

[ivanmilevtues]

@LilSpazJoekp I just added an integration for your readthedocs:

Take a look and let me know. This will update the docs every sunday or you can trigger it manually from the actions menu.

[LilSpazJoekp]

Could you rebase on main, squash commits to a single commit, and force push. I tried to do it myself but it looks you have maintainer editing turned off for the branch.

For the CI file, I have this:

name: CodeBoarding Documentation update workflow

on:
  schedule:
    - cron: '0 20 * * 0'  # Every Sunday at 8:00 PM UTC
  workflow_dispatch:
    inputs:
      repository_url:
        description: 'Repository URL to analyze'
        required: false
        default: 'https://github.com/praw-dev/praw'
        type: string
      source_branch:
        description: 'Source branch to analyze'
        required: false
        default: 'main'
        type: string
      target_branch:
        description: 'Target branch for documentation'
        required: false
        default: 'main'
        type: string
      output_directory:
        description: 'Output directory for documentation files'
        required: false
        default: '.codeboarding'
        type: string
      output_format:
        description: 'Output format for documentation'
        required: false
        default: '.rst'
        type: choice
        options:
          - '.rst'
          - '.md'
          - '.mdx'
  push:
    branches:
      - main

jobs:
  update-docs:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0  # Required to access branch history

      # Determine branches based on context
      - name: Set branch variables
        id: set-branches
        run: |
          if [ "${{ github.event.inputs.source_branch }}" != "" ] && [ "${{ github.event.inputs.target_branch }}" != "" ]; then
            echo "source_branch=${{ github.event.inputs.source_branch }}" >> $GITHUB_OUTPUT
            echo "target_branch=${{ github.event.inputs.target_branch }}" >> $GITHUB_OUTPUT
            echo "repository_url=${{ github.event.inputs.repository_url || format('https://github.com/{0}', github.repository) }}" >> $GITHUB_OUTPUT
          else
            echo "source_branch=main" >> $GITHUB_OUTPUT
            echo "target_branch=main" >> $GITHUB_OUTPUT
            echo "repository_url=https://github.com/${{ github.repository }}" >> $GITHUB_OUTPUT
          fi

      - name: Fetch CodeBoarding Documentation
        timeout-minutes: 30
        id: codeboarding
        uses: CodeBoarding/[email protected]
        with:
          repository_url: ${{ steps.set-branches.outputs.repository_url }}
          source_branch: ${{ steps.set-branches.outputs.source_branch }}
          target_branch: ${{ steps.set-branches.outputs.target_branch }}
          output_directory: ${{ github.event.inputs.output_directory || '.codeboarding' }}
          output_format: ${{ github.event.inputs.output_format || '.rst' }}

      - name: Display Action Results
        run: |
          echo "Documentation files created: ${{ steps.codeboarding.outputs.markdown_files_created }}"
          echo "JSON files created: ${{ steps.codeboarding.outputs.json_files_created }}"
          echo "Documentation directory: ${{ steps.codeboarding.outputs.output_directory }}"
          echo "JSON directory: ${{ steps.codeboarding.outputs.json_directory }}"
          echo "Has changes: ${{ steps.codeboarding.outputs.has_changes }}"

      # Move .rst files from .codeboarding/ to docs/architecture_overview/ folder
      - name: Move .rst files to architecture overview
        run: |
          # Create docs/architecture_overview directory if it doesn't exist
          mkdir -p docs/architecture_overview
          
          # Check if .codeboarding/ exists and contains .rst files
          if [ -d ".codeboarding" ] && [ -n "$(find .codeboarding -name '*.rst' -type f)" ]; then
            echo "Moving .rst files from .codeboarding/ to docs/architecture_overview/"
          
            # Copy .rst files to docs/architecture_overview folder
            cp .codeboarding/*.rst docs/architecture_overview/ 2>/dev/null || echo "No .rst files found to copy"
          
            # Also copy any subdirectories with .rst files
            find .codeboarding -type d -exec sh -c '
              for dir do
                if [ -n "$(find "$dir" -maxdepth 1 -name "*.rst" -type f)" ]; then
                  echo "Copying .rst files from $dir"
                  cp "$dir"/*.rst docs/architecture_overview/ 2>/dev/null || echo "No .rst files found in $dir"
                fi
              done
            ' sh {} +
          
            echo ".rst files moved to architecture overview successfully"
          else
            echo "No .codeboarding/ directory or .rst files found"
          fi

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip pre-commit
          pip install .[dev]
      - name: Run hooks
        run: pre-commit run --all-files

      - uses: peter-evans/create-pull-request@v7
        with:
          branch: update/codeboarding-docs
          title: Update CodeBoarding documentation
          commit-message: Update CodeBoarding documentation
          body: |
            - Documentation files created/updated: ${{ steps.codeboarding.outputs.markdown_files_created }}
            - JSON files created/updated: ${{ steps.codeboarding.outputs.json_files_created }}

This adds our documentation formatter and simplifies the pull request process.