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

Switching documentation to use the jupyter-book structure #544

Merged
merged 26 commits into from
Apr 15, 2024

Conversation

elbeejay
Copy link
Contributor

@elbeejay elbeejay commented Dec 12, 2023

Overhauling the documentation to use the jupyter-book format based on the template.

Converted the gld/Support/A - Guides and Documentation/GLD_Manual_V.1.0.docx file into an .md file with pandoc but still need to manually go in and clean up the formatting.

  • clean up manual formatting (.md file) - will likely need another few passes to catch everything... it's a long file

Similarly, an initial take on dynamic generation of a page with the harmonization script hierarchy and links to each .do file has been started, but I need to get the GitHub workflow fixed and check the formatting of the output .md file more closely.

  • check and finalize formatting for dynamic hierarchy documentation

There are a bunch of stubs and placeholders in the documentation, and some redundancies (multiple locations and files for contributing for example) that I'll attempt to trim down and set some basic information in as well.

  • fill-out stubs, delete redundant pages

Will mark this as "Ready" once complete, but wanted to keep you both in the loop @g4brielvs and @gronert-m

@g4brielvs g4brielvs self-requested a review December 12, 2023 07:01
@elbeejay elbeejay marked this pull request as ready for review December 22, 2023 15:40
@elbeejay
Copy link
Contributor Author

Apologies for the delay, got caught up in other things for a bit here.

The long and short of it is that this PR:

  • Formats the documentation using the "template" jupyter-book structure
  • Converted and formatted the .docx manual as a .md file and included it in the documentation
  • Dynamically generated a file structure for the .do scripts in the repository with links to the individual files
  • Places "stub" notes in the short bits of documentation that are not fully explained (@gronert-m will need you to look at the rendered documentation and decide which pages to delete and which to keep and add text to)
  • Ensure links/images etc. show up properly

It's entirely likely that further revisions to the manual will be needed for formatting, it was quite a long document and the translation of the formatting from Word to Markdown was not as automatic as Pandoc made me think it might be, so I very well could have missed something when going through it manually.

@g4brielvs it's a lot of changes, for a review I'd suggest you checkout the branch and build the documentation locally and have a quick look. @gronert-m was very open to an iterative approach to improving this documentation, so once you sign off on this we can get it merged and built, which will make the new documentation easy for him to view and provide additional feedback on.

Thanks all.

@g4brielvs
Copy link
Contributor

g4brielvs commented Dec 22, 2023

@elbeejay Thanks! In regard to build/workflow, it works and it closes #541. I'll defer to @gronert-m to review/provide feedback on the content. A preview is available at this link (a different link just to preserve the current documentation).

Copy link
Contributor

@g4brielvs g4brielvs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In regard to build/workflow, it works!

@g4brielvs g4brielvs requested a review from gronert-m December 22, 2023 17:38
@g4brielvs g4brielvs added the documentation Improvements or additions to documentation label Dec 22, 2023
@elbeejay elbeejay linked an issue Jan 31, 2024 that may be closed by this pull request
@elbeejay
Copy link
Contributor Author

@gronert-m - we are pending your approval and merge for this documentation to go live.

@elbeejay
Copy link
Contributor Author

@gronert-m what's the plan here? The branch is only going to get more stale and there are only going to be additional conflicts as files change. Is there anything you'd like changed or revised here before this is merged?

@gronert-m gronert-m merged commit 62a644e into main Apr 15, 2024
2 checks passed
@gronert-m gronert-m deleted the switch-to-wb-doc-template branch April 17, 2024 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Development

Successfully merging this pull request may close these issues.

Switch Documentation to Jupyter Book
3 participants