Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README - mdBook in Cargo.toml #3860

Open
DJStompZone opened this issue Mar 13, 2024 · 1 comment
Open

README - mdBook in Cargo.toml #3860

DJStompZone opened this issue Mar 13, 2024 · 1 comment

Comments

@DJStompZone
Copy link

πŸ‘€ I have searched open and closed issues and pull requests for duplicates, using these search terms:

  • "mdbook"
  • "mdbook this file"
  • "mdbook cargo.toml"

βœ… I have checked the latest main branch to see if this has already been fixed, in this file:

  • README.md (line 27)

🌐URL to the section(s) of the book with this problem:

README.md, line 27

πŸ’¬ Description of the problem:

The readme says "Building the book requires mdBook, ideally the same version that
rust-lang/rust uses in this file". However, mdBook being in its own category rather than under the generic "dependencies" section makes it easy to miss, creating the potential for confusion. (Frankly, when I started typing this issue, I myself was convinced it was missing, and only noticed it after doing a ctrl+f search to double check)

πŸ”¨ Suggested fix:

Dynamically insert the correct version for mdBook in the readme in order to make the documentation more clear, concise, and welcoming. This can be done with minimal difficulty via GitHub Actions:

  1. Update README.md ✏

- Building the book requires [mdBook], ideally the same version that
+ Building the book requires [mdBook], ideally version ${mdBook_version}
- rust-lang/rust uses in [this file][rust-mdbook]. To get it:
+ To get it:
- $ cargo install mdbook --version <version_num>
+ $ cargo install mdbook --version ${mdBook_version}
  1. Create workflow 🎬

name: Update mdBook Version in README

on:
  push:
    paths:
      - '**/Cargo.toml'

jobs:
  update-readme:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
      
      - name: Update README.md with actual mdBook version
        run: |
          NEW_VERSION=$(grep -oP 'version = "\K(.*)(?=")' Cargo.toml | tail -1)
          OLD_VERSION=$(grep -oP '\$ cargo install mdbook --version \K([0-9.]+)' README.md)
          if [ ! -z "$OLD_VERSION" ] && [ "$NEW_VERSION" != "$OLD_VERSION" ]; then

            # Update README.md, line 26
            sed -i "s|Building the book requires \[mdBook\], ideally version $OLD_VERSION|Building the book requires [mdBook], ideally version $NEW_VERSION|g" README.md

            # Update README.md, line 33
            sed -i "s|\$ cargo install mdbook --version $OLD_VERSION|\$ cargo install mdbook --version $NEW_VERSION|g" README.md

            git config --global user.name 'github-actions'
            git config --global user.email '[email protected]'
            git add README.md
            git commit -m "Update mdBook version to $NEW_VERSION in README" -m "This automatic commit updates the mdBook version directly in the README.md to match the version specified in Cargo.toml." || echo "No changes to commit"
            git push
          else
            echo "mdBook version is already up-to-date or not found in README.md."
          fi

Cheers!

--DJ

@chriskrycho
Copy link
Contributor

Thanks for the suggestion! We'll need to decide whether we want to add that automation (automation is awesome but also has to be maintained over time!), but having a handy example is fantastic!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants