toddfarmer commented on code in PR #193: URL: https://github.com/apache/arrow-cookbook/pull/193#discussion_r880575964
########## java/CONTRIBUTING.rst: ########## @@ -1,13 +1,27 @@ Building the Java Cookbook ========================= - The Java cookbook uses the Sphinx documentation system. -Running ``make java`` from the cookbook root directory (the one where -the ``README.rst`` exists) will install all necessary dependencies -and will compile the cookbook to HTML. +Dependencies +------------------------- +The following are required to successfully build the Java cookbook: + +Python +^^^^^^^^^^^^^^^^^^^^^^^^^ +The cookbook build tooling depends upon Python, and the ability to +install needed packages via pip, to build the Java cookbook. The +dependency packages managed via pip by build scripts are found at +`requirements.txt <requirements.txt>`_. + +sphinx-build +^^^^^^^^^^^^^^^^^^^^^^^^^ +Building the Java cookbook requires Sphinx build tools: -For java cookbook we are running these with Java Shell tool - +`sphinx-build <https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`_ Review Comment: I've attempted to reproduce the error I documented earlier caused by missing `sphinx-build`, but have only had limited success. Generally speaking, the installation of the requirements.txt modules satisfies everything, and I am able to build successfully. The only time I was able to trigger the error again was after a successful build, deleting the contents of `/home/todd/.local/bin` directory, which included `sphinx-build`: ``` todd@pop-os:~/arrow-cookbook$ which sphinx-build /home/todd/.local/bin/sphinx-build todd@pop-os:~/arrow-cookbook$ ls /home/todd/./local/bin ls: cannot access '/home/todd/./local/bin': No such file or directory todd@pop-os:~/arrow-cookbook$ ls /home/todd/.local/bin black pycodestyle rst2man.py rstpep2html.py blackd pyflakes rst2odt_prepstyles.py sphinx-apidoc black-primer pygmentize rst2odt.py sphinx-autogen flake8 rst2html4.py rst2pseudoxml.py sphinx-build isort rst2html5.py rst2s5.py sphinx-quickstart pybabel rst2html.py rst2xetex.py __pycache__ rst2latex.py rst2xml.py todd@pop-os:~/arrow-cookbook$ rm -rf /home/todd/.local/bin/* todd@pop-os:~/arrow-cookbook$ which sphinx-build todd@pop-os:~/arrow-cookbook$ make java >>> Installing Java Dependencies <<< cd java && pip install -r requirements.txt Defaulting to user installation because normal site-packages is not writeable Requirement already satisfied: Sphinx>=4.0.2 in /home/todd/.local/lib/python3.10/site-packages (from -r requirements.txt (line 1)) (4.5.0) Requirement already satisfied: black==21.7b0 in /home/todd/.local/lib/python3.10/site-packages (from -r requirements.txt (line 2)) (21.7b0) Requirement already satisfied: flake8==3.8.3 in /home/todd/.local/lib/python3.10/site-packages (from -r requirements.txt (line 3)) (3.8.3) Requirement already satisfied: isort==4.3.21 in /home/todd/.local/lib/python3.10/site-packages (from -r requirements.txt (line 4)) (4.3.21) Requirement already satisfied: regex>=2020.1.8 in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (2022.4.24) Requirement already satisfied: pathspec<1,>=0.8.1 in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (0.9.0) Requirement already satisfied: appdirs in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (1.4.4) Requirement already satisfied: mypy-extensions>=0.4.3 in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (0.4.3) Requirement already satisfied: tomli<2.0.0,>=0.2.6 in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (1.2.3) Requirement already satisfied: click>=7.1.2 in /usr/lib/python3/dist-packages (from black==21.7b0->-r requirements.txt (line 2)) (8.0.3) Requirement already satisfied: mccabe<0.7.0,>=0.6.0 in /home/todd/.local/lib/python3.10/site-packages (from flake8==3.8.3->-r requirements.txt (line 3)) (0.6.1) Requirement already satisfied: pyflakes<2.3.0,>=2.2.0 in /home/todd/.local/lib/python3.10/site-packages (from flake8==3.8.3->-r requirements.txt (line 3)) (2.2.0) Requirement already satisfied: pycodestyle<2.7.0,>=2.6.0a1 in /home/todd/.local/lib/python3.10/site-packages (from flake8==3.8.3->-r requirements.txt (line 3)) (2.6.0) Requirement already satisfied: requests>=2.5.0 in /usr/lib/python3/dist-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.25.1) Requirement already satisfied: Pygments>=2.0 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.12.0) Requirement already satisfied: packaging in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (21.3) Requirement already satisfied: sphinxcontrib-devhelp in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.0.2) Requirement already satisfied: sphinxcontrib-jsmath in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.0.1) Requirement already satisfied: sphinxcontrib-qthelp in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.0.3) Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.0.0) Requirement already satisfied: docutils<0.18,>=0.14 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (0.17.1) Requirement already satisfied: alabaster<0.8,>=0.7 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (0.7.12) Requirement already satisfied: babel>=1.3 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.10.1) Requirement already satisfied: sphinxcontrib-applehelp in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.0.2) Requirement already satisfied: imagesize in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.3.0) Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.5 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.1.5) Requirement already satisfied: snowballstemmer>=1.1 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.2.0) Requirement already satisfied: Jinja2>=2.3 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (3.1.2) Requirement already satisfied: pytz>=2015.7 in /usr/lib/python3/dist-packages (from babel>=1.3->Sphinx>=4.0.2->-r requirements.txt (line 1)) (2022.1) Requirement already satisfied: MarkupSafe>=2.0 in /home/todd/.local/lib/python3.10/site-packages (from Jinja2>=2.3->Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.1.1) Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in /usr/lib/python3/dist-packages (from packaging->Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.4.7) >>> Building Java Cookbook <<< cd java && make html make[1]: Entering directory '/home/todd/arrow-cookbook/java' /bin/sh: 1: sphinx-build: not found make[1]: *** [Makefile:20: html] Error 127 make[1]: Leaving directory '/home/todd/arrow-cookbook/java' make: *** [Makefile:81: java] Error 2 ``` However, after explicitly removing the modules, re-running `make java` resulted in success: ``` todd@pop-os:~/arrow-cookbook/java$ pip uninstall -r requirements.txt Found existing installation: Sphinx 4.5.0 Uninstalling Sphinx-4.5.0: Would remove: /home/todd/.local/lib/python3.10/site-packages/Sphinx-4.5.0.dist-info/* /home/todd/.local/lib/python3.10/site-packages/sphinx/* Proceed (Y/n)? Successfully uninstalled Sphinx-4.5.0 Found existing installation: black 21.7b0 Uninstalling black-21.7b0: Would remove: /home/todd/.local/lib/python3.10/site-packages/_black_version.py /home/todd/.local/lib/python3.10/site-packages/black-21.7b0.dist-info/* /home/todd/.local/lib/python3.10/site-packages/black/* /home/todd/.local/lib/python3.10/site-packages/black_primer/* /home/todd/.local/lib/python3.10/site-packages/blackd/* /home/todd/.local/lib/python3.10/site-packages/blib2to3/* Proceed (Y/n)? Successfully uninstalled black-21.7b0 Found existing installation: flake8 3.8.3 Uninstalling flake8-3.8.3: Would remove: /home/todd/.local/lib/python3.10/site-packages/flake8-3.8.3.dist-info/* /home/todd/.local/lib/python3.10/site-packages/flake8/* Proceed (Y/n)? Successfully uninstalled flake8-3.8.3 Found existing installation: isort 4.3.21 Uninstalling isort-4.3.21: Would remove: /home/todd/.local/lib/python3.10/site-packages/isort-4.3.21.dist-info/* /home/todd/.local/lib/python3.10/site-packages/isort/* Proceed (Y/n)? Successfully uninstalled isort-4.3.21 todd@pop-os:~/arrow-cookbook/java$ cd .. todd@pop-os:~/arrow-cookbook$ make java >>> Installing Java Dependencies <<< cd java && pip install -r requirements.txt Defaulting to user installation because normal site-packages is not writeable Collecting Sphinx>=4.0.2 Using cached Sphinx-4.5.0-py3-none-any.whl (3.1 MB) Collecting black==21.7b0 Using cached black-21.7b0-py3-none-any.whl (141 kB) Collecting flake8==3.8.3 Using cached flake8-3.8.3-py2.py3-none-any.whl (72 kB) Collecting isort==4.3.21 Using cached isort-4.3.21-py2.py3-none-any.whl (42 kB) Requirement already satisfied: pathspec<1,>=0.8.1 in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (0.9.0) Requirement already satisfied: regex>=2020.1.8 in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (2022.4.24) Requirement already satisfied: mypy-extensions>=0.4.3 in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (0.4.3) Requirement already satisfied: appdirs in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (1.4.4) Requirement already satisfied: click>=7.1.2 in /usr/lib/python3/dist-packages (from black==21.7b0->-r requirements.txt (line 2)) (8.0.3) Requirement already satisfied: tomli<2.0.0,>=0.2.6 in /home/todd/.local/lib/python3.10/site-packages (from black==21.7b0->-r requirements.txt (line 2)) (1.2.3) Requirement already satisfied: pyflakes<2.3.0,>=2.2.0 in /home/todd/.local/lib/python3.10/site-packages (from flake8==3.8.3->-r requirements.txt (line 3)) (2.2.0) Requirement already satisfied: mccabe<0.7.0,>=0.6.0 in /home/todd/.local/lib/python3.10/site-packages (from flake8==3.8.3->-r requirements.txt (line 3)) (0.6.1) Requirement already satisfied: pycodestyle<2.7.0,>=2.6.0a1 in /home/todd/.local/lib/python3.10/site-packages (from flake8==3.8.3->-r requirements.txt (line 3)) (2.6.0) Requirement already satisfied: sphinxcontrib-applehelp in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.0.2) Requirement already satisfied: alabaster<0.8,>=0.7 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (0.7.12) Requirement already satisfied: imagesize in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.3.0) Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.0.0) Requirement already satisfied: babel>=1.3 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.10.1) Requirement already satisfied: requests>=2.5.0 in /usr/lib/python3/dist-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.25.1) Requirement already satisfied: packaging in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (21.3) Requirement already satisfied: sphinxcontrib-qthelp in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.0.3) Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.5 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.1.5) Requirement already satisfied: sphinxcontrib-devhelp in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.0.2) Requirement already satisfied: Pygments>=2.0 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.12.0) Requirement already satisfied: Jinja2>=2.3 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (3.1.2) Requirement already satisfied: snowballstemmer>=1.1 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.2.0) Requirement already satisfied: docutils<0.18,>=0.14 in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (0.17.1) Requirement already satisfied: sphinxcontrib-jsmath in /home/todd/.local/lib/python3.10/site-packages (from Sphinx>=4.0.2->-r requirements.txt (line 1)) (1.0.1) Requirement already satisfied: pytz>=2015.7 in /usr/lib/python3/dist-packages (from babel>=1.3->Sphinx>=4.0.2->-r requirements.txt (line 1)) (2022.1) Requirement already satisfied: MarkupSafe>=2.0 in /home/todd/.local/lib/python3.10/site-packages (from Jinja2>=2.3->Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.1.1) Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in /usr/lib/python3/dist-packages (from packaging->Sphinx>=4.0.2->-r requirements.txt (line 1)) (2.4.7) Installing collected packages: isort, flake8, black, Sphinx Successfully installed Sphinx-4.5.0 black-21.7b0 flake8-3.8.3 isort-4.3.21 >>> Building Java Cookbook <<< cd java && make html make[1]: Entering directory '/home/todd/arrow-cookbook/java' Running Sphinx v4.5.0 WARNING: html_static_path entry '_static' does not exist loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 7 source files that are out of date updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found preparing documents... done writing output... [100%] schema generating indices... genindex done writing additional pages... search done copying static files... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded, 1 warning. The HTML pages are in build/html. make[1]: Leaving directory '/home/todd/arrow-cookbook/java' mkdir -p build/java cp -r java/build/html/* build/java ``` I will update the PR to eliminate the reference to needing `sphinx-build` explicitly installed. -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
