Skip to content

docs: refresh outdated README examples and versions - #169

Open
SatvikMishra08 wants to merge 1 commit into
ekalinin:masterfrom
SatvikMishra08:docs/165-readme-refresh
Open

SatvikMishra08 wants to merge 1 commit into
ekalinin:masterfrom
SatvikMishra08:docs/165-readme-refresh

Conversation

@SatvikMishra08

Copy link
Copy Markdown

Fixes #165.

README-only refresh for outdated examples and version pins:

  • Align Usage / Auto-insert TOC indent examples with the CLI default (--indent 3, see tests/tests.bats)
  • Regenerate the README <!--ts-->…<!--te--> TOC to match current output
  • Bump GitHub Actions example pins: actions/checkout@v7, stefanzweifel/git-auto-commit-action@v7
  • Update public Docker tag from 0.7.0 to 0.10.0 (matches gh_toc_version / Docker Hub)
  • Refresh the Tests section (11 active tests; remote/mixed tests are commented out)
  • Update “tested on” notes to current CI (ubuntu-latest)
  • Fix Combo URL typo (sitemap.s → sitemap.js)

No code / feature changes. README headings are unchanged so bats heading assertions stay valid.

Fixes ekalinin#165.

- Align TOC indent examples with default --indent 3
- Regenerate README <!--ts-->…<!--te--> TOC
- Bump Actions pins to checkout@v7 and git-auto-commit-action@v7
- Update Docker Hub tag to 0.10.0
- Refresh tests blurb (11 tests) and tested-on notes
- Fix Combo URL typo (sitemap.s → sitemap.js)
@ekalinin

Copy link
Copy Markdown
Owner

Thanks for working on this!

This branch is based on 97f764a, and #170-#174 have been merged into master since then, so some of the refreshed sections are already out of date. Also, several example outputs look like they were re-indented by hand instead of regenerated, so they don't match what the tool prints now. Could you rebase onto current master and regenerate each example by running ./gh-md-toc on it?

Details below (line numbers refer to README.md in this PR).

Out of date after rebase

  • Tests section (~L385): master now has 17 active tests. fix(remote): keep page markup out of the first TOC entry #170 re-enabled the remote/mixed tests, and there are new ones: "TOC for remote non-english chars", "Error for local file without network access" and two "TOC with depth ..." tests. So "remote/mixed tests are commented out" is no longer true. The hand-maintained list goes stale with every new test, so it might be simpler to just show make test with a short generic summary.
  • Local files example (L102): it has two leading blank lines and no <!-- Created by ... --> footer, but master's new --depth example right next to it shows the footer. For a single local file the real output is one blank line, the TOC, a blank line and the footer.

Examples that don't match real output

  • Dockerfile.vim (L85, L105-106, L224-225): "Or using Pathogen:" and "Or using Vundle:" are h4 headings, so with the default --indent 3 they get 9 spaces, not 3.
  • envirius (L127): the current output also has "Table of Contents", "Export environment into tar archive", "Import environment from tar archive" and the footer. The nodeenv wiki example (L180) has the same problem: the real output also includes edx, HSReplay.net, sailing-channels.com, Galaxy and more.
  • Multiple files (L192): aminb/rust-for-c has moved to bandali/rust-for-c. gh_toc_load runs curl without -L, so the redirect isn't followed and the TOC comes out empty. Two of the four pages (primitive_types_and_operators, unique_pointers) return 404 even after the redirect. This example needs different URLs.
  • Combo (L228): the URL works now that sitemap.s is fixed, but the output shown isn't what the tool prints for that page. The real output starts with badge markup and has other entries ("Table of Contents", "Generate a one time sitemap from a list of urls", ...). Also, the shell expands ~/projects/..., so the real links contain absolute paths, not ~.
  • --insert example (L278):
    • The first run's output doesn't have "Table of contents" or "Auto insert and update TOC", but the grep afterwards shows both in the file.
    • Without --hide-footer, both <!-- Created by ... --> and <!-- Added by ... --> get inserted, but only "Added by" is shown, and its ISO date isn't what $(date) produces.
    • There are 16 lines after <!--ts-->, so grep -A15 doesn't reach <!--te-->.
    • stdout would also include "Found markers".
  • docker images (L444): the IMAGE ID column is missing, so "11 minutes ago" is in the IMAGE ID position. For a pulled image, CREATED shows the build date (2024-03-03), not the pull time, and 147MB is the size of the 0.7.0 image.

Examples that fail when copied

  • Docker 0.10.0 (L441): the image was built in March 2024 from the 0.10.0 tag and doesn't include the remote-parsing fix from fix(remote): keep page markup out of the first TOC entry #170. Running the documented docker run ... envirius/README.md prints GitHub page markup (<button data-component="Button" ...) as the first entry. The image also doesn't support --depth.
  • GitHub Actions (L367): please add permissions: contents: write. git-auto-commit-action needs it to push with GITHUB_TOKEN. Without it, repos where the default token is read-only get a 403 in the commit step.

"Tested on" wording (L20, L411)

CI has a single ubuntu-latest job that runs bats under bash. There's no macOS job, and nothing runs zsh. The old text said macOS High Sierra was tested with release 0.4.9. The new wording drops that qualifier and puts macOS and zsh next to the CI mention. Could you reword it so CI is only mentioned for Ubuntu/bash?

Nit

This repo uses type(scope): subject commit messages. Could you rename the commit and PR title to something like docs(readme): refresh outdated examples and versions?

This branch has not been deployed

No deployments
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.

Update outdated examples and versions in README

2 participants