capitalone/DataProfiler

Fix broken hyperlink in the documentation

rakeshgowerneni opened this issue · 14 comments

rakeshgowerneni commented

Please provide the issue you face regarding the documentation
The hyperlink in the below sentence in the Load a File section should change from

If the file type is not automatically identified (rare), you can specify them specifically, see section Specifying a Filetype or Delimiter.

to

If the file type is not automatically identified (rare), you can specify them specifically, see section Specifying a Filetype or Delimiter.

I am trying to fix the documentation as a way to create my first PR on the repo.

JGSweets commented

@rakeshgowerneni that's a good catch! I'm curious why sphinx did not generate that properly. Thoughts on how to fix? We welcome PRs and would love to see you contribute!

taylorfturner commented

@rakeshgowerneni -- Check out our contribution guide here for creating pull requests.

taylorfturner commented

When you implement the fix @rakeshgowerneni, be sure its not specifying a specific version in the hyperlink. Rather, it should be agnostic to the version and just resolve to the proper location within whatever docs are live at that time.

If the file type is not automatically identified (rare), you can specify them specifically, see section [Specifying a Filetype or Delimiter](https://capitalone.github.io/DataProfiler/docs/0.10.1/html/profiler.html?highlight=filetype#specifying-a-filetype-or-delimiter).

thebadcoder96 commented

Hey is anyone working on this? Can I try this out?

  • ❤️1
taylorfturner commented
taylorfturner commented

@thebadcoder96 let me know if you have anymore questions -- the team is back at it today. Thanks for your interest!

  • ❤️1
thebadcoder96 commented

Thank you for the response! I will go through the readme file that you mentioned and let you know if I have any questions.

  • ❤️1
taylorfturner commented

Thank you for the response! I will go through the readme file that you mentioned and let you know if I have any questions.

Thanks @thebadcoder96!

thebadcoder96 commented

Here is how I think we can solve the issue. I do not have much idea on sphinx but I am looking into that as well.

  • We can run a Python script that prints out the current/live version of Data Profiler.
  • Trigger a custom GitHub Actions workflow when there is a push to main and use the Python script to update the readme file using the latest version. Probably use sed for updating the readme file.

Wdyt? Any other thoughts are welcome since I do not have full context on how everything works within the Data Profiler, I might be wrong as well.

taylorfturner commented

I think we can actually re-use the code written out here.

That script will have:

  • the proper version tag
  • we can simply find the spot in the pertinent file to ensure its always referencing the most up-to-date build of the docs.

That should work! For updating docs, all changes will happen on your fork's branch of dev-gh-pages and you will make the changes in docs/update_documentation.py or docs/src. Once you get that point, though, just ping me and I'll be glad to answer any questions (or feel free to add to README for gh-pages branches for improved direction clarity)

thebadcoder96 commented

Please correct me if I am wrong, but the issue mentioned here pertains to the readme file of the Data Profiler Github. In the documentation website there is no hyperlink and the sentence is also a bit different.

From my understanding, docs/update_documentation.py updates the GitHub pages documentation, which is NOT the one we want to update right?

  • 👍1
taylorfturner commented

@thebadcoder96 yes, you are correct. I was confusing something else.

In this case I would key off of the version.py file and try to reference that in the README.md as a consistent reference point for the proper version for the hyperlink... there might be another way too to reference the index.html and tack on a #specifying-a-hyoerlink(or something like that) to the hyperlink in the README

taylorfturner commented

@thebadcoder96 the URL should be

https://capitalone.github.io/DataProfiler/docs/<current_version_tag>/html/profiler.html?highlight=filetype#specifying-a-filetype-or-delimiter

We'll want the version tag to be a reference and not a manual change every time we make a new release of dataprofiler.

thebadcoder96 commented

Since you mentioned version tag, I think we can use git describe --tags to get the current version tag and then update the readme file.

I have created a PR with the proposed changes, please review #1080