Skip to content
This repository has been archived by the owner on Jul 3, 2023. It is now read-only.

Redo documentation setup #69

Closed
4 tasks done
elijahbenizzy opened this issue Feb 9, 2022 · 9 comments · Fixed by #270
Closed
4 tasks done

Redo documentation setup #69

elijahbenizzy opened this issue Feb 9, 2022 · 9 comments · Fixed by #270

Comments

@elijahbenizzy
Copy link
Collaborator

elijahbenizzy commented Feb 9, 2022 •
edited by skrawcz
Loading

Is your feature request related to a problem? Please describe.
Currently, gitbooks syncs with a specific documentation branch. This does not guarentee that it syncs with releases though.

Describe the solution you'd like
If gitbooks.io doesn't allow for this, let's look at a statically hosted page using github pages or some other hosting service. Ideally we'd even be able to version it with the release version so you can see old docs.

We should consider read the docs for hosting -- since it seems to be the default for python projects of scale.

Tasks:

Some examples of docs to emulate:
gitbook-com bot pushed a commit that referenced this issue Feb 21, 2022
@skrawcz @gitbook-bot
GitBook: [#69] No subject
309486c
@jameslamb
Copy link
Contributor

Ah, a documentation branch! I was wondering where the docs at https://hamilton-docs.gitbook.io/docs/ came from.

Ideally we'd even be able to version it with the release version so you can see old docs.

In LightGBM, we've had a great experience for 4+ years with the readthedocs service. It allows for building different versions of your docs from source control based on git tags.

microsoft/LightGBM#4236 (comment)

https://lightgbm.readthedocs.io/en/latest/

Screen Shot 2022-03-27 at 4 04 29 PM

@skrawcz skrawcz mentioned this issue Apr 29, 2022
Closed
@elijahbenizzy
Copy link
Collaborator Author

@jameslamb would love to learn from your experience with lightgbm -- that's a very sleek look. Where's a good place to start?

@jameslamb
Copy link
Contributor

@elijahbenizzy sure! I also just set up readthedocs ("RTD") on one of my little side projects, so I have recent experience doing this. Would be happy to get on a call with you and @skrawcz some time and pair if you'd like.

Here's a high-level overview:

  1. go to https://readthedocs.org/accounts/login/ and log in with your GitHub
  2. click "import a project", and import hamilton
    • that'll reserve hamilton.readthedocs.io, and default to building from the main branch on every commit to main (no more separate documentation branch)
  3. set up a .readthedocs.yaml config file at the root of the repo, telling RTD how to build your docs
  4. once that's all set up, you can enable the "allow people to flip between different versions" thing from my screenshot above by modifying RTD's settings such that it builds from specific tags (which it calls "versions")
    • here's an example from the setting page for lightgbm.readthedocs.io
    • image

Hope that helps!

@elijahbenizzy
Copy link
Collaborator Author

@jameslamb thak you -- this is great! Sorry it just slipped my mind recently -- I think I'll be able to get this started, but I'll reach out once I have something! 🙏

@skrawcz skrawcz changed the title Synchronize Gitbooks with main branch Redo documentation Dec 13, 2022
@skrawcz skrawcz changed the title Redo documentation Redo documentation setup Dec 13, 2022
@frenchfrywpepper
Copy link
Contributor

Stefan or Elijah - Can you create an account at https://readthedocs.org/ then tell me your username? Then I can invite you to the Hamilton project there.

After that you'll be able to see the webhook and configure it on GitHub following these Instructions

@skrawcz
Copy link
Collaborator

skrawcz commented Dec 20, 2022

@frenchfrywpepper awesome thanks! skrawcz.

frenchfrywpepper pushed a commit to frenchfrywpepper/hamilton that referenced this issue Jan 10, 2023
WIP: Migrate documentation from gitbooks to readthedocs
4fdb95d 
Issue stitchfix#69

- [] Scope what's required to set up read the docs
- Create a readthedocs account for the https://github.com/stitchfix/hamilton repo, add multiple administrators
- Enable build on merge to main, this will be published as the 'latest' documentation version
- Create some configuration in the docs folder to tell read the docs how to behave
- Create some configuration in the docs folder to use sphinx/rst/furo theme, etc
- Move the .md files from the documentation branch and reconfigure them as .rst
- [] Determine how it would function and be rebuilt.
- Read the docs will automatically build on merge to main, and publish as latest
- If you want to add another 'version' you can activate a new version in the read the docs settings for the project, this can be done by branch or tag
- If you don't want to build 'latest' from main you can turn that off
- [] Get something set up -- determine styling.
- In this PR I have something setup and working, with minimal style. It's building "hamilton-temp" documentation from my fork.
- You can see the 'readthedocs' version here: https://hamilton-temp.readthedocs.io/en/readthedocs/
- You can see the 'latest' version here: https://hamilton-temp.readthedocs.io/en/latest/index.html
- I've created placeholder pages for all of the current docs, this is to ensure the TOC is working as desired
- Only the intro page has content and links and such, if we like this direction the next step would be to convert more pages to rst
- This setup is using the furo theme, further customization is possible, but I'd recommend getting all of the content moved over first.
- [] Plan migration from gitbooks.
- Get all the content moved over to rst on the 'main' branch of hamilton
- Setup all of the versions to be built
- Turn off gitbooks?
- Delete 'documentation' branch
@frenchfrywpepper frenchfrywpepper mentioned this issue Jan 10, 2023
Merged
11 tasks
@frenchfrywpepper
Copy link
Contributor

Question: How important are the description sections to you? Is it important that they have unique formatting? Let's say they can't be uniquely formatted in rst, would you still want them there, just as regular text?

How it looks in gitbook...

Screenshot 2023-01-25 at 2 57 02 PM

How it looks in read the docs...

https://hamilton-temp.readthedocs.io/en/readthedocs/index.html

@elijahbenizzy
Copy link
Collaborator Author

Question: How important are the description sections to you? Is it important that they have unique formatting? Let's say they can't be uniquely formatted in rst, would you still want them there, just as regular text?

How it looks in gitbook...

Screenshot 2023-01-25 at 2 57 02 PM

How it looks in read the docs...

https://hamilton-temp.readthedocs.io/en/readthedocs/index.html

Don't think they're super important. Pretty sure they can either be dropped or included as the first line in the new version. Looking good!

skrawcz pushed a commit that referenced this issue Jan 31, 2023
@skrawcz
WIP: Migrate documentation from gitbooks to readthedocs
500597c 
Issue #69

- [] Scope what's required to set up read the docs
- Create a readthedocs account for the https://github.com/stitchfix/hamilton repo, add multiple administrators
- Enable build on merge to main, this will be published as the 'latest' documentation version
- Create some configuration in the docs folder to tell read the docs how to behave
- Create some configuration in the docs folder to use sphinx/rst/furo theme, etc
- Move the .md files from the documentation branch and reconfigure them as .rst
- [] Determine how it would function and be rebuilt.
- Read the docs will automatically build on merge to main, and publish as latest
- If you want to add another 'version' you can activate a new version in the read the docs settings for the project, this can be done by branch or tag
- If you don't want to build 'latest' from main you can turn that off
- [] Get something set up -- determine styling.
- In this PR I have something setup and working, with minimal style. It's building "hamilton-temp" documentation from my fork.
- You can see the 'readthedocs' version here: https://hamilton-temp.readthedocs.io/en/readthedocs/
- You can see the 'latest' version here: https://hamilton-temp.readthedocs.io/en/latest/index.html
- I've created placeholder pages for all of the current docs, this is to ensure the TOC is working as desired
- Only the intro page has content and links and such, if we like this direction the next step would be to convert more pages to rst
- This setup is using the furo theme, further customization is possible, but I'd recommend getting all of the content moved over first.
- [] Plan migration from gitbooks.
- Get all the content moved over to rst on the 'main' branch of hamilton
- Setup all of the versions to be built
- Turn off gitbooks?
- Delete 'documentation' branch
@skrawcz skrawcz linked a pull request Jan 31, 2023 that will close this issue
Migrate documentation from gitbooks to readthedocs #270
Merged
11 tasks
@skrawcz
Copy link
Collaborator

skrawcz commented Jan 31, 2023 •
edited
Loading

Closing this because most of it is done, with follow up tasks of #295 and #297.

@skrawcz skrawcz closed this as completed Jan 31, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Migrate documentation from gitbooks to readthedocs frenchfrywpepper/hamilton
4 participants
@frenchfrywpepper @skrawcz @elijahbenizzy @jameslamb