[
https://issues.apache.org/jira/browse/ARROW-12188?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Joris Van den Bossche updated ARROW-12188:
------------------------------------------
Description:
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.
was:
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).
----
Probably it 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.
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
> [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
> Fix For: 4.0.0
>
>
> 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)
