Skip to content

Doc improve#1105

Merged
spoorcc merged 9 commits intomainfrom
doc-improve
Apr 3, 2026
Merged

Doc improve#1105
spoorcc merged 9 commits intomainfrom
doc-improve

Conversation

@spoorcc
Copy link
Copy Markdown
Contributor

@spoorcc spoorcc commented Apr 3, 2026

Summary by CodeRabbit

  • Documentation

    • Standardized command examples to terminal-style blocks with explicit "$" prompts across guides and tutorials.
    • Clarified SBOM behavior: licenses are detected at report time and left empty when missing or unrecognized.
  • Chores

    • Improved docs build/version resolution and configured full repository checkout for documentation workflows.
    • Updated internal documentation references and build configuration.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 3, 2026

Warning

Rate limit exceeded

@spoorcc has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 6 minutes and 17 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 6 minutes and 17 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: fae779a6-cb5a-4e79-a75b-a50ab8044626

📥 Commits

Reviewing files that changed from the base of the PR and between d4bcac0 and 5c36f35.

📒 Files selected for processing (3)
  • doc/howto/migration.rst
  • doc/howto/updating-projects.rst
  • doc/tutorials/getting_started.rst

Walkthrough

Sphinx config now derives the package version via importlib.metadata with a PackageNotFoundError fallback; latex_documents tuple was reformatted. Many docs examples were converted to console blocks with leading shell prompts. Docs workflow checkout uses full history. Importlinter pointer updated in pyproject.toml.

Changes

Cohort / File(s) Summary
Sphinx configuration
doc/conf.py
Stop importing __version__ from the package; derive via importlib.metadata.version("dfetch") with PackageNotFoundError"0.0.0" fallback. Reformat latex_documents tuple to multi-line.
Howto guides (prompts & SBOM)
doc/howto/adding-a-project.rst, doc/howto/sbom.rst, doc/howto/troubleshooting.rst, doc/howto/updating-projects.rst, doc/howto/check-ci.rst, doc/howto/patching.rst, doc/howto/migration.rst
Convert shell examples to console blocks and prefix commands with $ (or > for PowerShell examples); update SBOM text to state license detection occurs at report time and leave license empty when unknown; some minor reordering/indentation in migration guide.
Tutorials & installation
doc/tutorials/getting_started.rst, doc/tutorials/installation.rst
Add explicit shell prompts ($/>) to command examples and convert blocks to console; adjust indentation and replace Windows MSI example with winget (MSI shown as alternative).
Command docs (examples)
dfetch/commands/diff.py, dfetch/commands/format_patch.py, dfetch/commands/update_patch.py, dfetch/manifest/project.py
Switch example blocks from sh to console and add leading $ to example invocations and related example commands.
Docs CI workflow
.github/workflows/docs.yml
Set actions/checkout steps to fetch-depth: 0 to fetch full repository history for docs jobs.
Project config (importlinter)
pyproject.toml
Remove inline ASCII layer diagram/note and point importlinter contract to Architecture.rst; keep existing layers ordering contract.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

Suggested labels

documentation

Suggested reviewers

  • ben-edna
🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title 'Doc improve' is vague and generic, using non-descriptive terms that don't convey meaningful information about the changeset's specific improvements. Replace with a more specific title that describes the main documentation changes, such as 'Convert shell code examples to console directive with prompts' or 'Standardize documentation code-block formatting and command examples'.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch doc-improve

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@doc/tutorials/installation.rst`:
- Around line 68-70: The powershell code-block shows a Unix `$` prompt; update
the snippet so it's consistent: either change the code-block language from
`powershell` to `sh`/`console` if you want to keep the `$ msiexec /i
dfetch-<version>-win.msi` line as-is, or keep `.. code-block:: powershell` and
replace the prompt with PowerShell style (e.g., `>` or `PS>`), and if you use
copybutton adjust `copybutton_prompt_text` to include the chosen prompt so copy
behavior remains correct; locate the snippet containing `$ msiexec /i
dfetch-<version>-win.msi` to make the change.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a53d1ac0-4a10-4bd9-a074-c525758d462d

📥 Commits

Reviewing files that changed from the base of the PR and between 2bd62cc and 1db6051.

📒 Files selected for processing (7)
  • doc/conf.py
  • doc/howto/adding-a-project.rst
  • doc/howto/sbom.rst
  • doc/howto/troubleshooting.rst
  • doc/howto/updating-projects.rst
  • doc/tutorials/getting_started.rst
  • doc/tutorials/installation.rst

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@doc/tutorials/installation.rst`:
- Around line 66-76: Remove the Winget installation method by deleting the lines
containing the winget command and its surrounding explanatory text (the code
block with "> winget install dfetch" and the preceding sentence), and replace
that paragraph with the correct installation option such as a short sentence and
code block showing "pip install dfetch" (keep the existing .msi instructions
intact); ensure the erroneous "winget install dfetch" string is no longer
present so users only see supported install methods.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ed1e9a82-ebc8-4531-bdcd-556b5990ba48

📥 Commits

Reviewing files that changed from the base of the PR and between 1db6051 and 1b4b528.

📒 Files selected for processing (3)
  • .github/workflows/docs.yml
  • doc/tutorials/installation.rst
  • pyproject.toml

Comment on lines +66 to +76
Install dfetch directly through winget:

.. code-block:: powershell

msiexec /i dfetch-<version>-win.msi
> winget install dfetch

Or download the ``.msi`` installer from the releases page and install by double-clicking or use:

.. code-block:: powershell

> msiexec /i dfetch-<version>-win.msi
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🌐 Web query:

What is the exact Winget package identifier for dfetch, and what is the recommended command format (including --id and --exact) for deterministic installs?

💡 Result:

There is no Winget package identifier for dfetch. dfetch (dfetch-org/dfetch) provides Windows .msi installers on GitHub releases, but no evidence of a manifest in the official winget-pkgs repository or other sources was found across multiple searches targeting Winget packages, manifests, and official documentation. It is not available via Winget. Install via pip (pip install dfetch) or download the .msi manually from https://github.com/dfetch-org/dfetch/releases.

Citations:


Remove the Winget installation method—dfetch is not available via Winget.

dfetch is not available in the official Winget package repository. The winget install dfetch command will not work. Users should install via pip install dfetch or download the .msi installer from the releases page instead. Remove this installation method from the documentation.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@doc/tutorials/installation.rst` around lines 66 - 76, Remove the Winget
installation method by deleting the lines containing the winget command and its
surrounding explanatory text (the code block with "> winget install dfetch" and
the preceding sentence), and replace that paragraph with the correct
installation option such as a short sentence and code block showing "pip install
dfetch" (keep the existing .msi instructions intact); ensure the erroneous
"winget install dfetch" string is no longer present so users only see supported
install methods.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@spoorcc, you're absolutely right — I apologize for the incorrect review comment! winstall.app is powered by an API that regularly checks Microsoft's official repository for Windows Package Manager apps, meaning it always provides the latest data. The listing at https://winstall.app/apps/DFetch-org.DFetch confirms that dfetch is indeed now available in the winget repository with package ID DFetch-org.DFetch.

My original search simply didn't find it because it was very recently published. The documentation is correct.

One optional minor suggestion: you could use the fully qualified ID for a more deterministic install command, to avoid potential future conflicts if another package matches dfetch:

> winget install --id DFetch-org.DFetch --exact

But this is entirely up to you — the current winget install dfetch is perfectly fine for now.


✏️ Learnings added
Learnt from: spoorcc
Repo: dfetch-org/dfetch PR: 1105
File: doc/tutorials/installation.rst:66-76
Timestamp: 2026-04-03T19:40:16.108Z
Learning: dfetch (dfetch-org/dfetch) IS available via Windows Package Manager (winget) with the package ID `DFetch-org.DFetch`. The winget install command `winget install dfetch` is valid. Do not flag winget installation instructions for dfetch as incorrect.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.


🧠 Learnings used
Learnt from: spoorcc
Repo: dfetch-org/dfetch PR: 904
File: script/package.py:10-18
Timestamp: 2026-01-02T22:46:53.305Z
Learning: In dfetch's script/package.py, importing dfetch.__version__ directly is acceptable and intentional; if dfetch is not installed in the environment, the packaging job should fail explicitly rather than handling the import error gracefully.

Learnt from: spoorcc
Repo: dfetch-org/dfetch PR: 861
File: .github/workflows/build.yml:120-125
Timestamp: 2025-12-25T23:52:41.740Z
Learning: In macOS PKG installers created with fpm for the dfetch project, the installation path `/opt/dfetch/opt/dfetch` is correct and intentional due to fpm's osxpkg prefix behavior (related to fpm issue `#1996`). This apparent path duplication should not be flagged as an error.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@doc/howto/updating-projects.rst`:
- Around line 108-110: The heading "parent repository::" has an extra colon that
causes Sphinx to treat it as a literal-block marker; change the text "parent
repository::" to "parent repository:" (remove one colon) so the following "..
code-block:: console" directive is recognized correctly and the literal block
behavior is removed.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 522e93e4-b835-4e7d-a49a-0e5b4dd7874c

📥 Commits

Reviewing files that changed from the base of the PR and between 1b4b528 and 85be36b.

📒 Files selected for processing (11)
  • dfetch/commands/diff.py
  • dfetch/commands/format_patch.py
  • dfetch/commands/update_patch.py
  • dfetch/manifest/project.py
  • doc/howto/adding-a-project.rst
  • doc/howto/check-ci.rst
  • doc/howto/patching.rst
  • doc/howto/sbom.rst
  • doc/howto/updating-projects.rst
  • doc/tutorials/getting_started.rst
  • doc/tutorials/installation.rst

Comment on lines +108 to +110
parent repository::

Dfetch (0.12.1)
.. code-block:: console
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Remove the literal-block marker before the directive.

Line 108 ends with ::, but Lines 110+ now use .. code-block:: console. Keep only one : (parent repository:) so Sphinx doesn’t treat this as a missing literal block.

Suggested fix
-parent repository::
+parent repository:
 
 .. code-block:: console
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
parent repository::
Dfetch (0.12.1)
.. code-block:: console
parent repository:
.. code-block:: console
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@doc/howto/updating-projects.rst` around lines 108 - 110, The heading "parent
repository::" has an extra colon that causes Sphinx to treat it as a
literal-block marker; change the text "parent repository::" to "parent
repository:" (remove one colon) so the following ".. code-block:: console"
directive is recognized correctly and the literal block behavior is removed.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@doc/howto/migration.rst`:
- Around line 25-26: Edit the intro sentence in doc/howto/migration.rst where it
currently reads "Before you start make sure your repository is fully up-to-date
and all submodules are initialised and checked out:" and insert a comma after
"Before you start" so it reads "Before you start, make sure your repository is
fully up-to-date and all submodules are initialised and checked out:".

In `@doc/tutorials/getting_started.rst`:
- Around line 213-214: The console block in the getting_started.rst snippet has
inconsistent indentation: the lines starting with "$ git add ext/test-repo-tag
ext-test-repo-tag.patch" and "$ git commit --amend --no-edit" use 3 leading
spaces instead of the 2-space indentation used by other console blocks; fix this
by adjusting those two lines to use exactly 2 leading spaces so the console
directive/output block matches the rest of the file and maintains uniform
formatting.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 863c31e4-45a5-435a-9a9b-062b82bb2309

📥 Commits

Reviewing files that changed from the base of the PR and between 85be36b and d4bcac0.

📒 Files selected for processing (3)
  • doc/howto/migration.rst
  • doc/howto/updating-projects.rst
  • doc/tutorials/getting_started.rst

@spoorcc spoorcc merged commit 1e2e358 into main Apr 3, 2026
38 checks passed
@spoorcc spoorcc deleted the doc-improve branch April 3, 2026 20:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant