New Theme Requests

[stevepiercy]

New Theme Requests

[stevepiercy]

See theming in Sphinx.

Review current Sphinx themes:

• Alabaster
• RTD
• Sentry Docs
• SphinxAwesome
• Insipid
• Material
• Executable Book

Style guide example:

• Sentry docs

[uralbash]

My two cents on this list:

• Have the option to configure github button, like alabaster theme.
• It would be cool to disappear sidebar on main page, see examples:
  • http://pyramid-sacrud.readthedocs.org/
  • http://docs.sqlalchemy.org/en/rel_1_0/

• where do sidebars fit into this? Sidebars in HTML markup often do not align with the content they reference, so the intended context is lost. Additionally code samples get squished and require horizontal scrolling. Example of both scenarios: http://docs.pylonsproject.org/projects/pyramid/en/master/narr/templates.html#debugging-templates To resolve this issue, I'd suggest using HTML styles that keep the sidebar within the flow of the page.

  For a long list in sidebar you need also to implement scrolling inside sidebar, see example: https://ziggurat-foundations.readthedocs.org/en/latest/changelog.html#id5

• It would also be nice to be able to hide sidebar by click like:
  • https://docs.python.org/3/
  • or http://pyramid-sacrud.readthedocs.org/pages/configuration.html

[stevepiercy]

Thanks for the examples and discussion, @uralbash. Regarding sidebars, I really like the implementation on passlib. It has most of the features you describe and a few more:

• Fixed position while scrolling main content
• Initially contracted sections
• Expands section contextually when scrolling
• Highlights sections contextually when scrolling
• Can be hidden and shown (I'd prefer a smooth transition)
• Search box is always visible.

It lacks scrolling in the sidebar, and I agree that should be added. Long lists otherwise get cut off until you reach the end of the page.

Every page should have a search box, including the index.

The SQLAlchemy site is an interesting integration of marketing and docs. Overall it is good, but has one serious failure on the marketing site: http://www.sqlalchemy.org/ Where are the docs in the main navigation? Oh, there it is, over on the right sidebar. OK, now I see why that decision was made, due to the many versions of SQLAlchemy.

Non-navigation sidebars like this one are a mistake. I don't like text flow to be in two columns. It works for print, but not online. We'll need to address that.

This will be a very challenging design problem.

[blaflamme]

For me one of the best docs implementation done is gitbook.com, as an example http://redux.js.org/index.html

The content should have a maximum width, or you loose all the usability of paragraphs and blocks, and then get long lines. The sidebar should be closable and sticky, srollable from the inside if too long.

[stevepiercy]

gitbook.com is a nice clean design and layout. Next and Previous are nice touches.

But it's intent is more of a tutorial approach than a jump-in-anywhere docs approach.

• Sidebar navigation content doesn't fit our model because it is site-wide instead of in-page.
• Search box scrolls up and out of view.

[blaflamme]

That's something I really dislike about how sphinx works and provide contextual navigation, you always feel lost and it's hard to compose docs. It has to scroll up out of view if there's more content than the viewport.

[stevepiercy]

@blaflamme see example of contextual navigation on passlib, which addresses that concern: https://pythonhosted.org/passlib/index.html

It doesn't make sense to have a navigation bar with the content of a table of contents (that belongs on a TOC page or an index), especially for Pyramid, due to its massive number of pages.

[blaflamme]

@stevepiercy yes I know that point, this is what I dislike about how sphinx works where you get too much deep level TOC and loose where you are inside the whole thing. Even if the web gives us the ability to link things «in space» and not by sequence, almost all documentation is done by sequence. I know a lot of people like it, or are used to it, it just doesn't feel right to me. I'm not saying we should do that, just express my thoughts.

[stevepiercy]

I don't think knowing where you are in the docs is important for Pyramid, except for its official tutorials.

Pyramid's API and p*-script docs are not sequential (unless you count alphabetic sort order as sequential). The official tutorials are sequential and should have order. There's also some meta material above API, tutorials, and narrative docs which lacks sequence. In the narrative docs, the only thing sequential about them is that they are grouped into essential concepts first, followed by advanced concepts: it's not linear, but more web-like and interconnected.

I never read the Pyramid docs sequentially, except when I'm revising them or going through tutorials. I read them when I want to learn about a concept or find the solution to a problem. For that I need a solid search feature.

[blaflamme]

Well... to me it seems like being grouped by concepts, interests or alphabetically is kind of a sequence (and structure) where you know where you are and can refer to previous material or concepts you've read before. Lacking knowing the structure is kind of hard to connect the dots while you need references, and doing a search to match things anywhere gives you results but also without context, you're then lost.

Lets say you're looking at the structure of our docs, then go to pyramid latest , and say you are interested in the p* scripts docs. Then you click first on pserve to read a bit, and then you figure out you need more information on pcreate. You can click on any links in the page and you'll never go back to the parent root level (which I would have wanted a TOC on the side to shows where I am and just click four menu above). Nothing's telling you where you are inside the whole documentation or in the group of ideas (or scripts here), that makes no sense to me to have to click back or do a search to just look at other information part of the same group or concept. We're far from basic usability :(

[stevepiercy]

OK, so I see what you mean. Sequence/Ordering/Linear is one type of structure, as are grouping, mapping, and hierarchy. Grouping into sections or and related concepts and providing a way to navigate therein makes sense.

I think what we are talking about is answering the question, "How do I find what I need?" more than, "Where am I?". The former is more important than the latter.

I don't learn in any well-defined and fixed order or structure. I'm more of a random access learner: I learn stuff as I need it. There's no way to predict when I will need something in any particular order. Also I don't understand every concept presented on a single page on the first time reading it. Sometimes I have to refer to another topic, then another, and so on, and eventually I will loop back to the original concept. But that has no predictable order.

Maybe what we want is Related Topics, Tags, Categories, or Clouds in a sidebar navigation?

Some organizational hierarchy is provided by breadcrumbs, but not in a consistent way: http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/index.html http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/requirements.html

[blaflamme]

@stevepiercy right, english is not my primary language so sometimes my ideas are not expressed accurately :(

I think the hierarchy is important because it makes things related or organized to each others. I learn in a circle way more than in straight line, and not in particular order depending of the topic. so I learn a bit of everything and go deeper as needed/requested so I always keep the big picture and make sense of the details according to the context/behaviour/sequence inside the whole.

Right, at least the breadcrumb helps here but that would be more convenient to navigate across the different steps/topics from the TOC inside the tutorial IMHO.

[blaflamme]

@stevepiercy Added Sentry Docs as reference to review, mitsuhiko did a great job at fixing some of my concerns.

[stevepiercy]

@blaflamme yeah, this is well-organized and well-structured documentation.

On laptop screens, I found a minor issue, where context might be difficult to figure out without some scrolling. It would be nice to have the navigation scroll to where you are or not to jump back to the top of the div. https://docs.getsentry.com/hosted/clients/python/integrations/pyramid/#logger-setup

I also added a link to an example of a style guide. Pyramid's needs improvement.