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.

Sign up for GitHub

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

Jump to bottom

Restructure docs #3303

Merged
merged 4 commits into from Dec 18, 2018
Merged

Restructure docs #3303

merged 4 commits into from Dec 18, 2018

Conversation

ashwinvis
Copy link
Contributor

Work in progress to fix #3301, suggestions welcome.

What has changed

  1. How-to -> Tutorials (separate page); Learn -> Resources (URL is the same)

@ColCarroll
Copy link
Member

This looks like a good suggestion to me -- thanks for the well written issue and for making the this pull request!

Once you are ready for detailed comments on this PR, I can build them on my machine and push them to a static site so we can try them live - please put a comment here letting me know!

A few responses to your points:

  1. Quickstart -> short and nice, but no follow up links to read more
    Strong agree on the "Quickstart" notebook. I have been hoping someone would go write a new one or rewrite the current one.
  2. this page is OK, in my opinion
    Agree!
  3. Examples -> This hides the “tutorials” or HOWTOs somewhere in the middle
    Good point - I like the suggestion you've made here. The examples gallery is a custom plugin that might be hard for you to change. I am not sure if this is possible, but what if I added the gallery view you showed at the top of the current Learn page?
  4. Learn - confusing title, as I was expecting to see tutorials. Could be renamed to “Resources” or similar
    That's fair. I really like the books + videos, and "Resources" sounds like a link that I would never click on :) I would suggest (as above) combining the "How-To" examples with the "Learn" page.

@junpenglao junpenglao mentioned this pull request Dec 17, 2018
Merged
@ashwinvis
Copy link
Contributor Author

ashwinvis commented Dec 17, 2018 •
edited

@ColCarroll:

  1. Quickstart: Quickstart should be rewritten. Few users would be willing to read the "history" if they are looking for a "quick" win. Credits should be given where it is due, but not in this page. But since it is about changing the content, I would avoid that in this issue/PR, it is upto you guys 💯
  2. --
  3. HOWTOs -> Learn page? : Maybe it is possible, I am not sure how. Yes, it needed a few hacks to get the gallery to be split into two pages, but I have managed to do that in this PR 😄 . The tutorials needs a dedicated page, and should be split into sub-headings like Basic / Getting started and Intermediate. Isn't that better than mixing it with another page? Could you @ColCarroll identify the HOWTO notebooks to put them in sub-headings like that?
  4. Learn: Resources is quite dull, true! Books + Videos seem better.

If rest of the @pymc-devs chime into an agreement I can make the necessary changes.

@junpenglao
Copy link
Member

  1. re Quickstart
    I think we should make https://docs.pymc.io/notebooks/api_quickstart.html to be the actual quick start, and change the current quickstart to something else

  2. sounds good

  3. I like what @ashwinvis does by having a dedicated tab

  4. Books + Videos +1

@ashwinvis
Reorder navbar, change of names
94eabc0 
Details
-------
Quickstart = API quickstart (no navbar link, linked big blue button + tutorials)
Learn -> Books+Videos
Quickstart(old) -> About PyMC3

* Added syntax highlighting to landing page code snippet
* Added see also section at the end of About PyMC3
* Classified Tutorials into Basic and How-Tos
@ashwinvis
Copy link
Contributor Author

See updated look here: #3301 (comment)

junpenglao
junpenglao approved these changes Dec 17, 2018
View reviewed changes
Copy link
Member

@junpenglao junpenglao left a comment

Choose a reason for hiding this comment

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

LGTM. @ColCarroll could you please build it offline on your website so we can see how it looks?

ColCarroll
ColCarroll reviewed Dec 18, 2018
View reviewed changes
docs/source/Makefile
@@ -190,3 +191,6 @@ pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

serve: html
Copy link
Member

Choose a reason for hiding this comment

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

i don't think http.server actually takes a --directory argument! (only confirmed on python 3.6.6)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hmm. Maybe they introduced it on python 3.7+. I will swap that with a simple cd.

@ColCarroll
Copy link
Member

Pushing to my site: https://colindcarroll.com/static/pymc3/

Note as before that absolute links don't work, but relative ones do (so the pymc3 logo takes you to my homepage).

Only nitpick is the empty "Other" section on the bottom of the "Tutorials" page. I did not take a close look at the runpy magic that is going on, but it looks really good in general, and I'm ok with merging!

Thanks again, @ashwinvis!

@junpenglao
Copy link
Member

junpenglao commented Dec 18, 2018 •
edited

Final nitpick:

  • Agree with Colin that you should remove the empty "Other" section on the bottom of the "Tutorials" page
  • https://docs.pymc.io/notebooks/variational_api_quickstart.html should also belongs to the "Tutorials" page (currently it is the last one in VI session)
  • renaming pymc3/docs/source/intro.rst to pymc3/docs/source/history.rst

@ashwinvis
Copy link
Contributor Author

The dangling "Other" section is javascript stuff, no guarantees, but I can have look at it. Will fix the rest for sure.

@ashwinvis
Final tweaks to doc restructure
6f8d164 
Backwards compatible `make serve`, no dangling "Other", "intro.rst" -> "history"
@ashwinvis
Copy link
Contributor Author

Thanks for the quick code reviews. This PR was a thank you gesture for helping me implement monte-carlo for a climate sensitivity exercise. Cheers 🎉

@twiecki
Copy link
Member

twiecki commented Dec 18, 2018

This looks great!

@junpenglao junpenglao merged commit fc523cc into pymc-devs:master Dec 18, 2018
@junpenglao
Copy link
Member

Great work @ashwinvis !!!

@ashwinvis ashwinvis deleted the doc/restructure branch December 18, 2018 12:20
@junpenglao junpenglao mentioned this pull request Dec 18, 2018
Merged
junpenglao added a commit that referenced this pull request Dec 19, 2018
@junpenglao
Restructure docs.pymc.io, add developer guide (#3311)
ff1227b 
* [WIP] Restructure docs.pymc.io, add developer guide

Following #3303, this is a further restructure of our website.
- Tutorial page include all our high level API guides (including theano.rst, prod_dist.rst, gp.rst etc)
- renaming of some notebooks (some of them does not have title)
- notebooks might appear under more than 1 categories (if it covers multiple topics)

* Further formatting

* Add developer guide

* edit developer guide

* small formatting

* further formatting

* final formatting

* really final formatting

* fix links

* small edit + another proof reading

* formatting
@junpenglao junpenglao mentioned this pull request Dec 19, 2018
Merged
twiecki pushed a commit that referenced this pull request Dec 20, 2018
@junpenglao @twiecki
Restructure docs.pymc.io, add developer guide (redo #3311)
f7cfe9c 
* [WIP] Restructure docs.pymc.io, add developer guide

Following #3303, this is a further restructure of our website.
- Tutorial page include all our high level API guides (including theano.rst, prod_dist.rst, gp.rst etc)
- renaming of some notebooks (some of them does not have title)
- notebooks might appear under more than 1 categories (if it covers multiple topics)

* Further formatting

* Add developer guide

* edit developer guide

* small formatting

* further formatting

* final formatting

* really final formatting

* fix links

* small edit + another proof reading

* formatting
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ColCarroll ColCarroll ColCarroll left review comments

@junpenglao junpenglao junpenglao approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Restructure the docs organization to make it beginner friendly
4 participants
@ashwinvis @ColCarroll @junpenglao @twiecki