You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "danepitkin (via GitHub)" <gi...@apache.org> on 2023/09/12 17:13:33 UTC
[GitHub] [arrow] danepitkin commented on a diff in pull request #36591: GH-36590: [Docs] Support Pydata Sphinx Theme 0.13
danepitkin commented on code in PR #36591:
URL: https://github.com/apache/arrow/pull/36591#discussion_r1323284347
##########
docs/source/conf.py:
##########
@@ -319,7 +340,7 @@
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
-html_logo = "_static/arrow.png"
+# html_logo = "_static/arrow.png"
Review Comment:
Should we delete if commented out?
##########
docs/source/_templates/docs-sidebar.html:
##########
@@ -1,25 +0,0 @@
-
Review Comment:
I actually really like the sidebar for navigation. Just an idea, but what if we move the items in the top bar (`Specifications and Protocols`, `Development`, etc.) back into the sidebar? I see the sup-options are still there once you click into the top level section.
##########
docs/source/index.rst:
##########
@@ -35,11 +37,216 @@ such topics as:
**To learn how to use Arrow refer to the documentation specific to your
target environment.**
+.. grid:: 2
+ :gutter: 4
+ :padding: 2 2 0 0
+ :class-container: sd-text-center
+
+ .. grid-item-card:: Format
+ :class-card: contrib-card
+ :shadow: none
+
+ Read about the Apache Arrow format
+ specifications and protocols.
+
+ +++
+
+ .. button-ref:: format
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the specifications
+
+ .. grid-item-card:: Developing
+ :class-card: contrib-card
+ :shadow: none
+
+ Find the documentation on the topic of
+ contributions, reviews, building of the libraries
+ from source, building of the documentation,
+ continuous integration, benchmarks and the
+ release process.
+
+ +++
+
+ .. button-ref:: developers
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the documentation
+
+Supported environments
+----------------------
+
+.. grid:: auto
Review Comment:
For some reason, I find the lmplementations hard to read when they are in the same row vs in a separate row each. What do you think of moving them back to being list-like?
##########
docs/source/index.rst:
##########
@@ -35,11 +37,216 @@ such topics as:
**To learn how to use Arrow refer to the documentation specific to your
target environment.**
+.. grid:: 2
+ :gutter: 4
+ :padding: 2 2 0 0
+ :class-container: sd-text-center
+
+ .. grid-item-card:: Format
+ :class-card: contrib-card
+ :shadow: none
+
+ Read about the Apache Arrow format
+ specifications and protocols.
+
+ +++
+
+ .. button-ref:: format
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the specifications
+
+ .. grid-item-card:: Developing
+ :class-card: contrib-card
+ :shadow: none
+
+ Find the documentation on the topic of
+ contributions, reviews, building of the libraries
+ from source, building of the documentation,
+ continuous integration, benchmarks and the
+ release process.
+
+ +++
+
+ .. button-ref:: developers
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the documentation
+
+Supported environments
+----------------------
+
+.. grid:: auto
+
+ .. grid-item::
+
+ .. button-ref:: c-glib
+ :ref-type: ref
+ :color: info
+ :shadow:
+
+ C/GLib
+
+ .. grid-item::
+
+ .. button-ref:: cpp
+ :ref-type: ref
+ :color: info
+ :expand:
+
+ C++
+
+ .. grid-item::
+
+ .. button-link:: https://github.com/apache/arrow/blob/main/csharp/README.md
+ :color: info
+ :expand:
+
+ C#
+
+ .. grid-item::
+
+ .. button-link:: https://pkg.go.dev/github.com/apache/arrow/go
+ :color: info
+ :expand:
+
+ Go
+
+ .. grid-item::
+
+ .. button-ref:: java
+ :ref-type: ref
+ :color: info
+ :expand:
+
+ Java
+
+ .. grid-item::
+
+ .. button-ref:: js
+ :ref-type: ref
+ :color: info
+ :expand:
+
+ JavaScript
+
+ .. grid-item::
+
+ .. button-link:: https://arrow.apache.org/julia/
+ :color: info
+ :expand:
+
+ Julia
+
+ .. grid-item::
+
+ .. button-link:: https://github.com/apache/arrow/blob/main/matlab/README.md
+ :ref-type: ref
+ :color: info
+ :expand:
+
+ Matlab
+
+ .. grid-item::
+
+ .. button-ref:: python
+ :ref-type: ref
+ :color: info
+ :expand:
+
+ Python
+
+ .. grid-item::
+
+ .. button-ref:: r
+ :ref-type: ref
+ :color: info
+ :expand:
+
+ R
+
+ .. grid-item::
+
+ .. button-link:: https://github.com/apache/arrow/blob/main/ruby/README.md
+ :color: info
+ :expand:
+
+ Ruby
+
+ .. grid-item::
+
+ .. button-link:: https://docs.rs/crate/arrow/
+ :color: info
+ :expand:
+
+ Rust
+
+`Implementation Status for all of the languages <status>`_
+
+Cookbooks
+---------
+
+.. grid::
+
+ .. grid-item::
+
+ .. button-link:: https://arrow.apache.org/cookbook/cpp/
+ :color: primary
+ :expand:
+
+ C++ cookbook
+
+ .. grid-item::
+
+ .. button-link:: https://arrow.apache.org/cookbook/java/
+ :color: primary
+ :expand:
+
+ Java cookbook
+
+ .. grid-item::
+
+ .. button-link:: https://arrow.apache.org/cookbook/py/
+ :color: primary
+ :expand:
+
+ Python cookbook
+
+ .. grid-item::
+
+ .. button-link:: https://arrow.apache.org/cookbook/r/
+ :color: primary
+ :expand:
+
+ R cookbook
+
+.. _toc.columnar:
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ format/index
+
+.. _toc.development:
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ developers/index
+
Review Comment:
IMO I would like the top level navigation to display more than `Specifications and Protocols` and `Development`. I like how the current layout focuses on implementation/examples first before getting into the specifications and development. I think it would be best to optimize for a new user coming to the docs rather than a new contributor.
My preference would be:
1. `Implementations` (contains Implementation status + Languages)
2. `Examples` (cookbooks)
3. `Specifications` (specification and protocols)
4. `Contributing` (development)
I think https://grpc.io/docs/ is a similar example of what I am envisioning (which is another project with specification + multiple language implementations). Something clean, simple, and intuitive to navigate quickly.
##########
docs/source/index.rst:
##########
@@ -35,11 +37,216 @@ such topics as:
**To learn how to use Arrow refer to the documentation specific to your
target environment.**
+.. grid:: 2
+ :gutter: 4
+ :padding: 2 2 0 0
+ :class-container: sd-text-center
+
+ .. grid-item-card:: Format
+ :class-card: contrib-card
+ :shadow: none
+
+ Read about the Apache Arrow format
+ specifications and protocols.
+
+ +++
+
+ .. button-ref:: format
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the specifications
+
+ .. grid-item-card:: Developing
+ :class-card: contrib-card
+ :shadow: none
+
+ Find the documentation on the topic of
+ contributions, reviews, building of the libraries
+ from source, building of the documentation,
+ continuous integration, benchmarks and the
+ release process.
+
+ +++
+
+ .. button-ref:: developers
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the documentation
+
+Supported environments
+----------------------
+
+.. grid:: auto
+
+ .. grid-item::
+
+ .. button-ref:: c-glib
+ :ref-type: ref
+ :color: info
+ :shadow:
Review Comment:
I'm personally not a fan of these buttons. The color and auto-sizing don't mesh with the existing theme well. I personally like the official support grid in https://grpc.io/docs/
##########
docs/source/conf.py:
##########
@@ -354,10 +375,9 @@
# Custom sidebar templates, maps document names to template names.
#
-html_sidebars = {
+# html_sidebars = {
# '**': ['sidebar-logo.html', 'sidebar-search-bs.html', 'sidebar-nav-bs.html'],
- '**': ['docs-sidebar.html'],
-}
+# }
Review Comment:
Should we delete here, too?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org