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

Sphinx/github docs tweaks to fix broken links #1286

Merged
merged 4 commits into from
Feb 22, 2024

Conversation

pgunn
Copy link
Member

@pgunn pgunn commented Feb 20, 2024

Attempts to fix #1278, also makes more docs available in sphinx/RTD and fixes some formatting

@pgunn
Copy link
Member Author

pgunn commented Feb 20, 2024

I am not entirely happy with how some of this works; I wasn't able to get any of the link-rewriting options to work, so I just revised the docs to not have those kinds of links. It solves the problem (and having more docs available in the doctree and fixing some of the unintended display issues in the doctree helps too).

There's more to fix here (tomorrow) because some of the docs I moved in don't render correctly. I might also see if there are other ways to rewrite URLs to make the cross-system each-link-with-local-semantics ideal happen, but we can actually do without that (because usually those links are actually bad content for things that make reading the docs feel scatterbrained); what's bad is the broken links.

@pgunn
Copy link
Member Author

pgunn commented Feb 20, 2024

Everything parses correctly now, even if some of the solutions here are not ideal. If we were to land this we'd fix many (all?) broken links on RTD and things would look better. I will still see tomorrow if there's a way to have consistent inner links within both distinct systems, but if we really needed to get this out the door this would at least be better than the way things are now.

@pgunn
Copy link
Member Author

pgunn commented Feb 20, 2024

(documenting for later that I tried recommonmark and MyST; neither seamlessly rewrote things and it was unclear how to add configuration requesting it do so)

@EricThomson
Copy link
Contributor

Looks good to me when I build locally and poke at things. It's hard to actually test locally that's part of the root cause of the problem, but seems good to go. There is a logo on the Overview page that's the only place I saw one in docs. We should consider whether we want to switch in new logo by keeping name same or changing name (if you know what I mean).

@pgunn
Copy link
Member Author

pgunn commented Feb 22, 2024

The new logo will be in a different diff, but I don't care either way about the filename we use for it.

@pgunn pgunn merged commit a9d598c into dev Feb 22, 2024
3 checks passed
@pgunn pgunn deleted the dev-sphinx_and_markdown_link_fixes branch March 5, 2024 20:57
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