search

numberscope / frontscope

Numberscope's front end and user interface: responsible for specifying sequences and defining and displaying visualizers
MIT License
7 stars 15 forks source link

doc: Restore broken and missing links #318

Closed gwhitney closed 5 months ago

gwhitney commented 5 months ago

By submitting this PR, I am indicating to the Numberscope maintainers that I have read and understood the contributing guidelines and that this PR follows those guidelines to the best of my knowledge. I have also read the pull request checklist and followed the instructions therein.

Over a number of commits, numerous missing and broken links in the MkDocs documentation for Numberscope had accumulated. This PR restores all MkDocs links to working order, including re-creating a section on submitting a pull request that had somehow been lost altogether in a previous documentation refactor.

When this commit is checked out, npm run doc:serve should not issue any warnings or info messages mentioning files that contain a link that do not correspond to any actual files or anchors in the system.

katestange commented 5 months ago

There's this file, should we integrate it with what you added.... ?https://github.com/numberscope/frontscope/blob/d0ea3a4c97e930dd167765b49a5d35e698f00a2a/doc/pull-request-checklist.md?plain=1#L2

Vectornaut commented 5 months ago

The fixes that have been made here look good, but I'm having trouble verifying that all the bad links have been fixed.

When I run doc:serve on the main branch, I only see one info or warning message about broken links: the one about the bad image link in the Entries user guide. The other broken links are still present, but when I search the doc:serve output for parts of the bad URLs (for example, "p5"), I don't find anything.

Is there some flag I need to set in order to get more messages?

gwhitney commented 5 months ago

The fixes that have been made here look good, but I'm having trouble verifying that all the bad links have been fixed.

When I run doc:serve on the main branch, I only see one info or warning message about broken links: the one about the bad image link in the Entries user guide. The other broken links are still present, but when I search the doc:serve output for parts of the bad URLs (for example, "p5"), I don't find anything.

Is there some flag I need to set in order to get more messages?

Make sure your main is fully up to date with the primary repo main, and have done npm install. Presuming so, here is the relevant part of the output of npm run doc:serve in main:

WARNING -  Doc file 'src/visualizers-workbench/P5VisualizerTemplate.md' contains a link
           '../../assets/img/Entries/1729.png', but the target 'assets/img/Entries/1729.png' is not found among
           documentation files. Did you mean '../assets/img/Entries/1729.png'?
INFO    -  Doc file 'CONTRIBUTING.md' contains a link './doc/working-with-git-and-github.md#basic-git-operations', but
           the doc 'doc/working-with-git-and-github.md' does not contain an anchor '#basic-git-operations'.
INFO    -  Doc file 'CONTRIBUTING.md' contains a link './doc/working-with-git-and-github.md#submit-a-pull-request', but
           the doc 'doc/working-with-git-and-github.md' does not contain an anchor '#submit-a-pull-request'.
INFO    -  Doc file 'CONTRIBUTING.md' contains a link './doc/gitting-it-right.md#add-a-remote', but the doc
           'doc/gitting-it-right.md' does not contain an anchor '#add-a-remote'.
INFO    -  Doc file 'CONTRIBUTING.md' contains a link './doc/gitting-it-right.md#sync-local-fork-with-remote-original',
           but the doc 'doc/gitting-it-right.md' does not contain an anchor '#sync-local-fork-with-remote-original'.
INFO    -  Doc file 'doc/gitting-it-right.md' contains a link './working-with-git-and-github.md#basic-git-operations',
           but the doc 'doc/working-with-git-and-github.md' does not contain an anchor '#basic-git-operations'.
INFO    -  Doc file 'doc/making-a-visualizer.md' contains a link '#p5-visualizers', but there is no such anchor on this
           page.
INFO    -  Doc file 'doc/making-a-visualizer.md' contains a link '#bulb-set-up-the-visualizer-often-used', but there is
           no such anchor on this page.
INFO    -  Documentation built in 0.18 seconds

All of these messages except the last one are gone in this PR branch.

gwhitney commented 5 months ago

There's this file, should we integrate it with what you added.... ?

https://github.com/numberscope/frontscope/blob/d0ea3a4c97e930dd167765b49a5d35e698f00a2a/doc/pull-request-checklist.md?plain=1#L2

Oh, good point. I will push a commit.

gwhitney commented 5 months ago

There's this file, should we integrate it with what you added.... ? https://github.com/numberscope/frontscope/blob/d0ea3a4c97e930dd167765b49a5d35e698f00a2a/doc/pull-request-checklist.md?plain=1#L2

Oh, good point. I will push a commit.

OK, I have now linked to the PR checklist. Also gave me the opportunity to fix the outline of the working with git page, and fix a couple typos. How's that look now?

katestange commented 5 months ago

OK, I have now linked to the PR checklist. Also gave me the opportunity to fix the outline of the working with git page, and fix a couple typos. How's that look now?

Great!

Vectornaut commented 5 months ago

and have done npm install

Oh, good—after npm install, I see the same messages on main, and can confirm that they're gone in fix_doc_links.

I agree that the section on submitting a pull request could use polishing, like you said in your e-mail, but I think something is better than nothing. I should be more free to work on that after May 4, so maybe it's a good candidate for a separate PR.

gwhitney commented 5 months ago

All right well nobody hold back on merging ;-)