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

Broken links in documentation #375

Closed
marshallmcdonnell opened this issue Jun 15, 2023 · 2 comments
Closed

Broken links in documentation #375

marshallmcdonnell opened this issue Jun 15, 2023 · 2 comments
Assignees

Comments

@marshallmcdonnell
Copy link
Contributor

marshallmcdonnell commented Jun 15, 2023

NOTE: This is related to JOSS review openjournals/joss-reviews#5467

Describe the bug
Broken links in docs throughout code base:

  1. Following link is broken in the docs for publishing datasets:
    https://github.com/MLMI2-CSSI/foundry/blob/main/docs/publishing/publishing-datasets.md?plain=1#L11

This line has the following link that does not exist:

[Skip to the publication example notebook.](https://github.com/MLMI2-CSSI/foundry/blob/master/examples/foundry_publication_example.ipynb)
  1. Broken link for contributing guide:
    https://github.com/MLMI2-CSSI/foundry/blob/main/docs/how-to-contribute/contributing.md?plain=1#L34

This line has the following link that does not exist:

* Tests should follow [testing best practices](https://www..org/community/contribute/tests)

To Reproduce
Try to navigate to these links.

Expected behavior
For (1), I expect that it is now a new name for the notebook and probably found here now?
https://github.com/MLMI2-CSSI/foundry/tree/main/examples/publishing-guides

@ascourtas
Copy link
Contributor

ascourtas commented Jan 2, 2024

Based on clicking around, it appears that some of the links in the actual GitBook documentation are not broken, but rather the docs hosted in the repo are significantly out of synch with the GitBook docs, thus making it confusing for the user. GitBook used to automatically synch, but in one of their updates that stopped working.

I'm going to reframe this issue to do the following:

  • Re-synch GitBook with GitHub to update the docs md files
  • Double check to make sure the GitBook links work
  • Ensure GitBook docs reflect current functionality

In future work, we may want to consider moving away from GitBook

@ascourtas
Copy link
Contributor

The GitBook - GitHub Integration has been fixed (thank you @blaiszik) and the /docs folder now reflects that. From here on all changes made in our documentation will be reflected in /docs. Changes can be viewed in commit 0fa7f19

The links to testing best practices were indeed broken in the current documentation, and have now been fixed and deployed in commit 68c8fbf

The link to our documentation is currently available in the GitHub repo's README, but please let us know if you think it needs to be more clearly communicated.

I will close this issue now that's resolved -- please feel free to reopen it if this solution didn't address all parts of the issue

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

No branches or pull requests

2 participants