Proposal for website design

Talked with @OriolAbril a bunch. Here are some thoughts I have on getting the website to a state where v4 can be released (a lot of them are already on the roadmap from Oriol):

There are three pages currently:

  1. with announcements and blog:
  2. Docs: PyMC Documentation — PyMC dev documentation
  3. Examples: PyMC example gallery — PyMC documentation

I think it’s confusing for users as they are not sure which to visit (at least between the first 2). They all have different versioning and code/repos, so harmonizing the code is probably out of scope. However, we can make them look similar. @OriolAbril had the idea to give them all the same navbar to make them look more similar and maybe the user doesn’t notice. I really like that.

The current navbar on the docs repo has:
I like this one the best and I think we should adopt it everywhere. Here’s how I propose the items and contents should be:

  • Home (currently spread across docs home and, I propose we use for this):
    • What is PyMC
    • Highlights (Fast, Modern, User-Friendly etc)
    • Links to installation instructions
    • Announcements
  • Examples (using PyMC example gallery — PyMC documentation but instead of its main page with descriptions about NBs, bring back the gallery like on v3 docs (not sure what to do with tags, maybe we make them invisible for now until we can combine it with the gallery). I also think here we can actually merge in gallary from the tutorials-selector from v3 and add these as additional categories. That way, all the NBs are in the same place.
  • Learning (like Learning Resources — PyMC3 3.11.5 documentation)
  • API (the amazing new API docs from API Reference — PyMC dev documentation)

I think we should remove the “Contributing” item. Here’s why: There are 4 types of people who could come to the site:

  1. People who don’t know what PyMC is (newcomers)
  2. People who already use PyMC and want to learn how to use it / solve their current problem (users)
  3. People who want to contribute (potential contributors)
  4. People who are already contributing (developers)

To narrow scope, I think we should optimize the website for newcomers and users, and have GitHub be optimized for potential contributors and developers.


I think part of the confusion between #1 and #2 is that #2 contains a lot of information that isn’t exactly “documentation”, but was placed there because we didn’t (at the time) have a place like #1 (except the README shown on github). If I were to land as #1 and saw a link to “Documentation” I wouldn’t expect to get what is currently at #2, (e…g, a high-level introduction to the package, its niceties, etc.). I would expect documentation. To me, it makes sense to try and get to be landing page and have documentation (API) and examples linked from there (along with other more static pymc info).

I personally would keep as a separated website. It is a different domain and it might be even more confusing for users to see the navbar maintained but different domains. AFAIK, all similar projects have multiple clearly separated websites:

Not a strong preference at all though.

I think that as @cluhmann points, now that we have we can restructure our websites (common navbar or not) to have a more sensible and coherent strucutre. IMO, the key, most important and irrenounceable difference between the websites are the different versioning schemes (which means they need to be build and updated independently from one another).
As I commented on slack:

  • has no versions. It is a single website that gets updated automatically
  • has versions tied to the versions of the pymc library, and defaults to showing the docs of the stable version
  • (aka pymc-examples) has independent versions/snapshots (2-3 a year, not necessarly tied to pymc releases) and defaults to latest . That means that new or updated notebooks show on the default website immediately instead of having to wait for a new release to see the changes

So answering which pages we want to have in each versioning scheme should indicate where should they be. i.e. we should probably move the community, maybe even contributing section to as I don’t think they need to be versioned following pymc releases. The homepage should also imo be because I don’t think the homepage should be versioned, it should have the highlights most important info about the library, not version specific content…

I very much agree with making the nabvar between docs and examples to be the same.

Also agreed on having the homepage at I would have more info on the homepage though (whatever theme/navbar we choose). See this comment for longer description on this.

Tags and a gallery looking page are completely independent, the tags are on the sidebar, we need to update the page content to write these cards with notebook titles. This should be possible combining code from pymc/ at v3 · pymc-devs/pymc · GitHub (to get the images from the notebooks) and arviz/ at main · arviz-devs/arviz · GitHub (to structure how to automatically write the rst/markdown page with the cards using sphinx-design). That being said, I don’t really know how sphinx extensions work and don’t want to maintain this alone if we go down this path.

I strongly disagree with removing the contributing element/section though.

  1. I think we should strive to make the division between user and contributor as blurry as possible, and I think this goes against this
  2. Most of the content is currently code based with some doc centric pages, but I think we should work on extending this, and not all contributions require using GitHub.
  3. I think it is much better to read pages rendered from the docs. We can use note/warning/tip boxes to highlight specific sentences, we can use tabs/dropdowns for alternative content or recommendations that are not vital to understanding all the page, we can link between pages and to api pages much more easily and robustly (we already use all this in different pages of the contributing section)
1 Like

Thanks @OriolAbril, sounds like we’re pretty aligned. I’m not strongly against keeping contributing there, so happy to defer there.

I think the main open questions are:

  1. Do we want all websites to look the same and share the navbar or only the docs and examples ones?
  2. What should be the items (and order) in the shared navbar?
  3. Who can work on and maintain the sphinx extension to generate the examples landing page with cards?
  4. What sections should there be in the main homepage at
  5. What should be the content in the learning or user guide section of the navbar
    • Some extra context. The new learning page doesn’t only have the content of the old page, it also has more “user guide” style content like the notebooks on core features. Those are a very small subset of notebooks that we decided should be versioned like pymc releases (and are therefore run on readthedocs when building the docs).

and also corollary from this is that closed questions are:

  • The main landing page is
  • We need to make the examples landing page more appealing
  • We’ll keep the contributing section in the navbar

As an average user of ‘apps’/‘libs’ that use multiple domains, I always get confused when the navbar changes across the domains. Actually I seldom look at the domain.

Moving from domain to domain, changes in the navbar typically make doubt whether I am still on the ‘official’ site(s), maybe looking at outdated stuff, etc

So my vote (or rather 2cts) go to ‘keep the navbar constant across domains’ :slight_smile:


My thoughts:

No installation, community, blog or about the project section? Everything must be inside one of these navbar sections, where would the blog, current community page, history, ecosystem, testimonial sections be if using these elements only? Or the installation instructions if we make the learning page be the v3 one

Should the search bar continue to be on the navbar? And icons on the right?

Re search bar, I think it would be crazy that the search bar returned different results depending on the page the user is in, given we are trying to hide the fact they are different websites from them. I can think of a way to solve this using the subprojecta feature which would then mean making everything a subproject of and everything being hosted at The PyMC project — Keeping up with PyMC

As I commented on github, here I would also add highlighted libraries that build on top of pymc and maybe some links to popular examples.

  • Installation instructions: We could add this, like scikit-learn does. But they are also on the home page. Correct me if I’m wrong but I think we don’t really currently have an installation page because we have 3 different installation instructions and I think that’s a good enough solution for now to link from the home page.
  • Community: Good point, maybe we should add that too. Maybe there we add the a link to the blog?
  • History: I don’t think we need that, could have that be a wiki page
  • Ecosystem: I don’t think we need that, we could have that as a section on the homepage as you say further below.
  • Testimonials: We could also have a few good ones on the home page

If we want to add just a bunch we could do what sklearn does and have a “More” fold-out that lists all of them that are important but not that often frequented that it needs a spot in the main navbar.

I would yes to the icons on the right.

Search bar: It’s a good issue you raise and the solution seems fine. I actually never used that feature and don’t have a strong intuition as to what results I would expect. Just search across everything, blog posts, tutorials, announcements, API? So I could do without the search bar.

We could add a thingy with the 3 tabs, that I think the new docs website supports

What do you mean “thingy with the 3 tabs”?

side note, we already have sphinx configured to use tabs, and use them. for example: Jupyter Style Guide — PyMC dev documentation

Yeah, that’s what I had in mind. Just didn’t know where we were using to link to xD

So to summarize where we are in regards to items in the navbar:

  • Home
  • Examples (Gallery)
  • Learning (Old videos + books page)
  • API
  • Community
  • Blog (?)