[jira] [Commented] (ARROW-12188) [Docs] Switch to pydata-sphinx-theme for the main sphinx docs

["David Li (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/ARROW-12188?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17313995#comment-17313995 ] 

David Li commented on ARROW-12188:
----------------------------------

IMO, I prefer #3 over #1 or #2. They might look cleaner, but it's annoying having to guess where to click to navigate (especially in #1 where everything is hidden under a very subtle dropdown).

I wouldn't mind #4 but it's easier to ctrl-F for something in #3. And while minor, #4 obscures that some of the language docs are not under Sphinx.

> [Docs] Switch to pydata-sphinx-theme for the main sphinx docs
> -------------------------------------------------------------
>
>                 Key: ARROW-12188
>                 URL: https://issues.apache.org/jira/browse/ARROW-12188
>             Project: Apache Arrow
>          Issue Type: Improvement
>          Components: Documentation
>            Reporter: Joris Van den Bossche
>            Assignee: Joris Van den Bossche
>            Priority: Major
>              Labels: pull-request-available
>             Fix For: 4.0.0
>
>          Time Spent: 20m
>  Remaining Estimate: 0h
>
> I have been working on using a new theme (the [pydata-sphinx-theme|https://pydata-sphinx-theme.readthedocs.io/en/latest/] with some custom styling for Arrow) for the sphinx documentation.
> Initially, I tried out a few variants (see below), but unless more people give their preference, I will keep the layout the same as it is now (a single sidebar, option 3 below).
> ----
> A few options for the layout, with a preview that I pushed to github pages:
> 1. Navbar + sidebar: the navbar contains the main sections (format, libraries, development), and then the sidebar further up to each page. 
>  Two example links: [https://jorisvandenbossche.github.io/arrow-docs-preview/html-option-1/format/CDataInterface.html] and [https://jorisvandenbossche.github.io/arrow-docs-preview/html-option-1/python/parquet.html]
> 2. Navbar with dropdown + sidebar: similar as above, but with an additional dropdown for the different libraries (languages). As a consequence, the sidebar only contains the items for one language (eg python) at a time (giving a better view if you're only looking at the python docs IMO, but needs more clicks to switch to another language). 
>  The same two example links: [https://jorisvandenbossche.github.io/arrow-docs-preview/html-option-2-dropdown/format/CDataInterface.html], [https://jorisvandenbossche.github.io/arrow-docs-preview/html-option-2-dropdown/python/parquet.html] (note that this option definitely still needs a better clue that you are eg in the python sub-part of the docs)
> 3. Only sidebar: this is similar in structure to what we have today with the RTD theme. 
>  The same two example links: [https://jorisvandenbossche.github.io/arrow-docs-preview/html-option-3-single-sidebar/format/CDataInterface.html], [https://jorisvandenbossche.github.io/arrow-docs-preview/html-option-3-single-sidebar/python/parquet.html]
> Lastly, I also made a option 4 that uses a single sidebar as option 3, but with a dropdown to choose the topic: https://jorisvandenbossche.github.io/arrow-docs-preview/html-option-4-sidebar-with-dropdown/format/CDataInterface.html, https://jorisvandenbossche.github.io/arrow-docs-preview/html-option-4-sidebar-with-dropdown/python/parquet.html
>  
> Probably those previews can be further improved with some additional (CSS) tweaks. I "just" took the orange-like color that is also used on the home page as the main color for the navigation, to give it a bit a custom touch.
> But so feedback on both which general structure you like most as details you would like to see improved is certainly welcome.
> An additional question is if we want to integrate this somehow with the navbar we already have from the home page.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)