apacheGH-35609: [Docs] Enable the build of subsections of the documen…

…tation (apache#35610)

### Rationale for this change

Ease the process of building the documentation for dev purposes.

### What changes are included in this PR?

- `make` options to build subsections of the documentation (format, developers, cpp together with existing python)
- `make` option for auto-build of the docs
- added info about the new make commands
* Closes: apache#35609

Lead-authored-by: Alenka Frim <frim.alenka@gmail.com>
Co-authored-by: AlenkaF <frim.alenka@gmail.com>
Signed-off-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>

docs/Makefile

@@ -26,24 +26,31 @@
 SPHINXOPTS    = -j8
 
 SPHINXBUILD   = sphinx-build
+SPHINXAUTOBUILD = sphinx-autobuild
 PAPER         =
 BUILDDIR      = _build
 SOURCEDIR     = source
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
+ALLSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# sphinx-autobuild needs an full absolute path for the ignored files
+CURRENT_DIR     = $(shell pwd)
+IGNORE_DIR      = $(CURRENT_DIR)/source/python/generated/*.rst
 
 .PHONY: help
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html           to make standalone HTML files"
+	@echo "  dev            to make only the developers documentation"
+	@echo "  format         to make only the format documentation"
+	@echo "  cpp            to make only the C++ documentation"
+	@echo "  python         to make only the Python documentation"
 	@echo "  dirhtml        to make HTML files named index.html in directories"
 	@echo "  singlehtml     to make a single large HTML file"
-	@echo "  python         to make only the Python documentation"
 	@echo "  pickle         to make pickle files"
 	@echo "  json           to make JSON files"
 	@echo "  htmlhelp       to make HTML files and a HTML help project"
@@ -76,12 +83,83 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf source/python/generated/*
 
+.PHONY: clean-dev
+clean-dev:
+	rm -rf $(BUILDDIR)/html/developers
+
+.PHONY: clean-format
+clean-format:
+	rm -rf $(BUILDDIR)/html/format
+
+.PHONY: clean-cpp
+clean-cpp:
+	rm -rf $(BUILDDIR)/html/cpp
+
+.PHONY: clean-python
+clean-python:
+	rm -rf $(BUILDDIR)/html/python
+	rm -rf source/python/generated/*
+
 .PHONY: html
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -b html $(SPHINXOPTS) source $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: html-live
+html-live:
+	$(SPHINXAUTOBUILD) -b html $(SPHINXOPTS) source $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+.PHONY: dev
+dev:
+	$(SPHINXBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/developers $(BUILDDIR)/html/developers
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/developers."
+
+.PHONY: dev-live
+dev-live:
+	$(SPHINXAUTOBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/developers $(BUILDDIR)/html/developers
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/developers."
+
+.PHONY: format
+format:
+	$(SPHINXBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/format $(BUILDDIR)/html/format
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/format."
+
+.PHONY: format-live
+format-live:
+	$(SPHINXAUTOBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/format $(BUILDDIR)/html/format
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/format."
+
+.PHONY: cpp
+cpp:
+	$(SPHINXBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/cpp $(BUILDDIR)/html/cpp
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/cpp."
+
+.PHONY: cpp-live
+cpp-live:
+	$(SPHINXAUTOBUILD) -c $(SOURCEDIR) $(SOURCEDIR)/cpp $(BUILDDIR)/html/cpp
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/cpp."
+
+.PHONY: python
+python:
+	$(SPHINXBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/python $(BUILDDIR)/html/python
+	@echo
+	@echo "Build finished. The HTML files are in $(BUILDDIR)/html/python"
+
+.PHONY: python-live
+python-live:
+	$(SPHINXAUTOBUILD) -b html $(SPHINXOPTS) --ignore $(IGNORE_DIR) -c $(SOURCEDIR) $(SOURCEDIR)/python $(BUILDDIR)/html/python
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/python."
+
 .PHONY: dirhtml
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -252,12 +330,6 @@ dummy:
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
 
-.PHONY: python
-python:
-	$(SPHINXBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/python $(BUILDDIR)/html/python
-	@echo
-	@echo "Build finished. The HTML files are in $(BUILDDIR)/html/python"
-
 java_tutorial:
 	$(SPHINXBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/java $(BUILDDIR)/html/tutorial/java
 	@echo

docs/requirements.txt

@@ -6,6 +6,7 @@ breathe
 ipython
 numpydoc
 pydata-sphinx-theme==0.8
+sphinx-autobuild
 sphinx-design
 sphinx-copybutton
 sphinx>=4.2,<6

docs/source/cpp/index.rst

@@ -18,8 +18,85 @@
 C++ Implementation
 ==================
 
+Welcome to the Apache Arrow C++ implementation documentation!
+
+.. grid:: 2
+   :gutter: 4
+   :padding: 2 2 0 0
+   :class-container: sd-text-center
+
+   .. grid-item-card:: Basic understanding
+      :class-card: contrib-card
+      :shadow: md
+
+      Start here to gain a basic understanding of Arrow with
+      an installation and linking guide, documentation of
+      conventions used in the codebase, tutorials etc.
+
+      +++
+
+      .. button-link:: getting_started.html
+         :click-parent:
+         :color: secondary
+         :expand:
+
+         Getting started
+
+   .. grid-item-card:: User Guide
+      :class-card: contrib-card
+      :shadow: md
+
+      Explore more specific topics and underlying concepts
+      of Arrow C++
+
+      +++
+
+      .. button-link:: user_guide.html
+         :click-parent:
+         :color: secondary
+         :expand:
+
+         User Guide
+
+.. grid:: 2
+   :gutter: 4
+   :padding: 2 2 0 0
+   :class-container: sd-text-center
+
+   .. grid-item-card:: Examples of use
+      :class-card: contrib-card
+      :shadow: md
+
+      Find the description and location of the examples
+      using Arrow C++ library
+
+      +++
+
+      .. button-link:: examples/index.html
+         :click-parent:
+         :color: secondary
+         :expand:
+
+         Examples
+
+   .. grid-item-card:: Reference documentation
+      :class-card: contrib-card
+      :shadow: md
+
+      Explore Arrow’s API reference documentation
+
+      +++
+
+      .. button-link:: api.html
+         :click-parent:
+         :color: secondary
+         :expand:
+
+         API Reference
+
 .. toctree::
    :maxdepth: 2
+   :hidden:
 
    getting_started
    user_guide

docs/source/developers/contributing.rst

@@ -46,7 +46,7 @@ All participation in the Apache Arrow project is governed by the ASF's
    :class-container: sd-text-center
 
    .. grid-item-card:: Community
-      :img-top: /developers/images/users-solid.svg
+      :img-top: ./images/users-solid.svg
       :class-card: contrib-card
       :shadow: md
 
@@ -63,7 +63,7 @@ All participation in the Apache Arrow project is governed by the ASF's
          Apache Arrow Community
 
    .. grid-item-card:: Bug reports
-      :img-top: /developers/images/bug-solid.svg
+      :img-top: ./images/bug-solid.svg
       :class-card: contrib-card
       :shadow: md
 
@@ -122,7 +122,7 @@ All participation in the Apache Arrow project is governed by the ASF's
    :class-container: sd-text-center
 
    .. grid-item-card:: New Contributors
-      :img-top: /developers/images/book-open-solid.svg
+      :img-top: ./images/book-open-solid.svg
       :class-card: contrib-card
       :shadow: md
 
@@ -142,7 +142,7 @@ All participation in the Apache Arrow project is governed by the ASF's
          New Contributor's guide
 
    .. grid-item-card:: Overview
-      :img-top: /developers/images/code-solid.svg
+      :img-top: ./images/code-solid.svg
       :class-card: contrib-card
       :shadow: md
 

docs/source/developers/documentation.rst

@@ -102,6 +102,8 @@ The final output is located under the ``${PWD}/docs`` directory.
 
    :ref:`docker-builds`.
 
+.. _building-docs-pr-preview:
+
 Building a docs preview in a Pull Request
 -----------------------------------------
 
@@ -111,7 +113,7 @@ To do so, post the comment ``@github-actions crossbow submit preview-docs``
 to the pull request. The rendered documentation will then be available within the
 GitHub Actions response, where you need to click on the Crossbow build badge:
 
-.. figure:: /developers/images/docs_preview_1.jpeg
+.. figure:: ./images/docs_preview_1.jpeg
    :scale: 70 %
    :alt: Github-actions response with the crossbow build status.
 
@@ -120,15 +122,90 @@ GitHub Actions response, where you need to click on the Crossbow build badge:
 and then in the summary of the workflow you can find the link to the Docs Preview
 summary at the bottom of the page:
 
-.. figure:: /developers/images/docs_preview_2.jpeg
+.. figure:: ./images/docs_preview_2.jpeg
    :scale: 70 %
    :alt: Crossbow workflow page with the Docs Preview summary section.
 
    Docs Preview summary section
 
+Building for dev purposes
+-------------------------
+
+Building subsections
+^^^^^^^^^^^^^^^^^^^^
+
+To make it easier for developers to update parts of the documentation, one can
+build only a subset of it. You can build:
+
+* Specifications and protocol section (``docs/source/format``) with:
+
+  .. code-block:: shell
+
+     pushd arrow/docs
+     make format
+     popd
+
+  Rendered HTML format can be found in ``arrow/docs/_build/html/format``.
+
+* Development section (``docs/source/developers``) with:
+
+  .. code-block:: shell
+
+     pushd arrow/docs
+     make dev
+     popd
+
+  Rendered HTML format can be found in ``arrow/docs/_build/html/developers``.
+
+* C++ section (``docs/source/cpp``) with:
+
+  .. code-block:: shell
+
+     pushd arrow/docs
+     make cpp
+     popd
+
+  Rendered HTML format can be found in ``arrow/docs/_build/html/cpp``.
+
+* Python section (``docs/source/python``) with:
+
+  .. code-block:: shell
+
+     pushd arrow/docs
+     make python
+     popd
+
+  Rendered HTML format can be found in ``arrow/docs/_build/html/python``.
+
+.. note::
+
+   When building only a part of the documentation the links will get broken!
+
+   For this reason building only a subset of the documentation should only be
+   used in the initial work as it makes the building faster and easier.
+
+   To check for the correctness of the documentation overall one should
+   build the whole documentation with ``make html`` or use
+   :ref:`GitHub Actions <building-docs-pr-preview>`.
+
+
+Building live
+^^^^^^^^^^^^^
+
+You can also build the documentation (or a part of it) live. This means the
+changes saved will automatically trigger the documentation to be rebuilt.
+
+.. code-block:: shell
+
+   pushd arrow/docs
+   make html-live
+
+The same way one could use ``make format-live``, ``make dev-live``, ``make cpp-live``
+or ``make python-live`` to auto-build part of the documentation.
+
 
 Building a single directory for dev purposes without all the pre-requisites
----------------------------------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can build documentation in a single directory without needing to install
 all of the pre-requisites by installing sphinx, setting up a temporary

docs/source/developers/guide/architectural_overview.rst

@@ -45,7 +45,7 @@ refer to:
 R package Architectural Overview
 --------------------------------
 
-.. figure:: /developers/images/R_architectural_overview.png
+.. figure:: ../images/R_architectural_overview.png
    :alt: Main parts of R package architecture: dplyr-*,
          dplyr-funcs*, tools, tests and src/.
 

docs/source/developers/guide/documentation.rst

@@ -57,13 +57,13 @@ requiring a lot of local development environment setup.
    on the right top corner of the documentations page. This
    will handle making a fork and a pull request for you.
 
-   .. figure:: /developers/images/edit_page.jpeg
+   .. figure:: ../images/edit_page.jpeg
       :scale: 20 %
       :alt: click on edit this page
 
       On the right corner of the file in GitHub click on pen icon.
 
-   .. figure:: /developers/images/github_edit_page.jpeg
+   .. figure:: ../images/github_edit_page.jpeg
       :scale: 30 %
       :alt: edit file in GitHub.