Skip to content

Our own llms.txt, built word for word from the docs, and every link checked - #232

Open
andrewbartels1 wants to merge 4 commits into
mainfrom
feat/own-llms-txt
Open

andrewbartels1 wants to merge 4 commits into
mainfrom
feat/own-llms-txt

Conversation

@andrewbartels1

Copy link
Copy Markdown
Owner

Queue item 19. Our own llms.txt, written fresh: nothing from #225 is used.

What changed

  • docs/llms.txt, served at the docs site's root, is generated from the mkdocs nav (python -m solidworks_mcp.doc_links build). Each entry's title is the page's # heading and its summary the page's first paragraph, copied word for word; links in it are reduced to their text. Nothing in it is written by hand.
  • A test fails when the committed file differs from a fresh build (it shows the expected and the found text for an entry), links anywhere but this project's site or repository, or holds HTML, comments, or invisible or text-direction characters.
  • Every link within the project (pages, files, heading anchors, blob/tree links into this repo) in the README, the docs and llms.txt is checked on every test run: 402 links, none broken.
  • Every link to another site is visited by python -m solidworks_mcp.doc_links check-external. It fails a dead link or a redirect to a different site, and writes a report of every URL. It runs after each docs deploy and weekly (a new link-check job in deploy-docs.yml), not in the unit tests.
  • Ten pages got a real opening paragraph to serve as their summary.

Security review

54 entries, every URL on our docs site, no HTML or hidden characters; every line read by hand. The COM pitfalls page opened with an instruction to AI assistants; that sentence moved out of the opening so llms.txt describes rather than instructs. The local-LLM page's opening carried a localhost address, moved to its second paragraph. Full notes: openspec/changes/own-llms-txt/design.md, decision 9.

First online run

145 URLs; 143 visited and passing, 2 listed as not checked with their reasons.

  • Your docs site address redirects. Every andrewbartels1.github.io/SolidworksMCP-python/... URL forwards to andrewbartels1.com/SolidworksMCP-python/..., the custom domain on your GitHub Pages site. It's allowed as the same site; you may prefer to make andrewbartels1.com the site_url.
  • console.anthropic.com/settings/keys moved to platform.claude.com; the link is updated.
  • GitHub rate-limits scripts on issue pages, so issue and PR links are checked through GitHub's API (with the CI token).
  • towardsdatascience.com (403) and www.solidworks.com (times out) refuse scripts. The checker doesn't pretend to be a browser; both are listed as "not checked" in the report.

Checks

  • Mock suite: 3,876 passed, 100% coverage.
  • ruff clean.
  • mkdocs build --strict OK; llms.txt lands at the site root unchanged.
  • openspec validate --all: 56 pass.

No live SolidWorks demo: nothing here touches SolidWorks.

The drawing-pack plan keeps the new 'After the clean-up' scenario, now
saying no tool is planned once the drawing pack is built.
…every link checked

docs/llms.txt is generated from the mkdocs nav: each entry's title and
summary are the page's heading and opening paragraph, copied word for
word. A test fails when the file and the pages disagree, when it links
outside this project, or when it holds HTML or hidden characters.

Links within the project (pages, files, anchors, repository files) are
checked on every test run; every link to another site after each docs
deploy and weekly, with a report of every URL. Ten pages got a real
opening paragraph; one moved link was updated. Queue item 19.
The !!python/name tags are replaced by null before parsing, so the
file goes through safe_load and no custom loader is needed.

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.

2 participants