[arvados] created: 2.6.0-505-g6214997f9
git repository hosting
git at public.arvados.org
Tue Aug 15 13:05:46 UTC 2023
at 6214997f9c61b40e25a31b9ca7d6b63b9a158837 (commit)
commit 6214997f9c61b40e25a31b9ca7d6b63b9a158837
Author: Brett Smith <brett.smith at curii.com>
Date: Mon Aug 14 17:04:10 2023 -0400
20853: Modernize pdoc installation process
Install to a virtualenv to accommodate PEP 668.
Arvados-DCO-1.1-Signed-off-by: Brett Smith <brett.smith at curii.com>
diff --git a/doc/README.textile b/doc/README.textile
index 045517107..9799ac564 100644
--- a/doc/README.textile
+++ b/doc/README.textile
@@ -20,11 +20,13 @@ arvados/doc$ bundle install
To generate the Python SDK documentation, these additional dependencies are needed:
<pre>
-arvados/doc$ sudo apt-get install python3-pip
-arvados/doc$ pip3 install arvados-python-client
-arvados/doc$ pip3 install pdoc
+arvados/doc$ sudo apt install python3-pip python3-venv
+arvados/doc$ python3 -m venv .venv
+arvados/doc$ .venv/bin/pip install pdoc
</pre>
+Then the generation process will need to be able to find @arvados/doc/.venv/bin/pdoc at . Either add that full directory to your @$PATH@, or make a @pdoc@ symlink in another directory that's already in your @$PATH at .
+
h2. Generate HTML pages
<pre>
commit 8c65e73116254f49c2311dcb3f0685312d14d275
Author: Brett Smith <brett.smith at curii.com>
Date: Mon Aug 14 17:00:57 2023 -0400
20853: Switch from pdoc3 to pdoc
pdoc is better maintained, both in terms of release cadence and in terms
of community code of conduct.
Arvados-DCO-1.1-Signed-off-by: Brett Smith <brett.smith at curii.com>
diff --git a/.gitignore b/.gitignore
index c15601803..557386b99 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,9 @@ docker/*/generated
docker/config.yml
doc/.site
doc/sdk/python/arvados
+doc/sdk/python/arvados.html
+doc/sdk/python/index.html
+doc/sdk/python/search.js
doc/sdk/R/arvados
doc/sdk/java-v2/javadoc
*/vendor
diff --git a/build/run-tests.sh b/build/run-tests.sh
index 765b31379..6a94d6ff1 100755
--- a/build/run-tests.sh
+++ b/build/run-tests.sh
@@ -653,7 +653,7 @@ install_env() {
. "$VENV3DIR/bin/activate"
# Needed for run_test_server.py which is used by certain (non-Python) tests.
- # pdoc3 needed to generate the Python SDK documentation.
+ # pdoc needed to generate the Python SDK documentation.
(
set -e
"${VENV3DIR}/bin/pip3" install wheel
@@ -664,7 +664,7 @@ install_env() {
"${VENV3DIR}/bin/pip3" install ciso8601
"${VENV3DIR}/bin/pip3" install pycurl
"${VENV3DIR}/bin/pip3" install ws4py
- "${VENV3DIR}/bin/pip3" install pdoc3
+ "${VENV3DIR}/bin/pip3" install pdoc
cd "$WORKSPACE/sdk/python"
python3 setup.py install
) || fatal "installing PyYAML and sdk/python failed"
diff --git a/doc/README.textile b/doc/README.textile
index 85757980a..045517107 100644
--- a/doc/README.textile
+++ b/doc/README.textile
@@ -22,7 +22,7 @@ To generate the Python SDK documentation, these additional dependencies are need
<pre>
arvados/doc$ sudo apt-get install python3-pip
arvados/doc$ pip3 install arvados-python-client
-arvados/doc$ pip3 install pdoc3
+arvados/doc$ pip3 install pdoc
</pre>
h2. Generate HTML pages
diff --git a/doc/Rakefile b/doc/Rakefile
index 89454940c..c9322bb6a 100644
--- a/doc/Rakefile
+++ b/doc/Rakefile
@@ -28,7 +28,7 @@ module Zenweb
end
end
-task :generate => [ :realclean, 'sdk/python/arvados/index.html', 'sdk/R/arvados/index.html', 'sdk/java-v2/javadoc/index.html' ] do
+task :generate => [ :realclean, 'sdk/python/arvados.html', 'sdk/R/arvados/index.html', 'sdk/java-v2/javadoc/index.html' ] do
vars = ['baseurl', 'arvados_cluster_uuid', 'arvados_api_host', 'arvados_workbench_host']
if ! ENV.key?('baseurl') || ENV['baseurl'] == ""
if !ENV.key?('WORKSPACE') || ENV['WORKSPACE'] == ""
@@ -50,7 +50,7 @@ file ["install/new_cluster_checklist_Azure.xlsx", "install/new_cluster_checklist
cp(t, t)
end
-file "sdk/python/arvados/index.html" do |t|
+file "sdk/python/arvados.html" do |t|
if ENV['NO_SDK'] || File.exist?("no-sdk")
next
end
@@ -58,10 +58,10 @@ file "sdk/python/arvados/index.html" do |t|
if $? == 0
raise unless system("python3", "setup.py", "build",
chdir: "../sdk/python", out: :err)
- raise unless system("pdoc", "--html", "-o", "sdk/python", "../sdk/python/build/lib/arvados/",
+ raise unless system("pdoc", "-o", "sdk/python", "../sdk/python/build/lib/arvados/",
out: :err)
else
- puts "Warning: pdoc3 not found, Python documentation will not be generated".colorize(:light_red)
+ puts "Warning: pdoc not found, Python documentation will not be generated".colorize(:light_red)
end
end
@@ -202,6 +202,8 @@ end
task :clean do
rm_rf "sdk/python/arvados"
+ rm_f "sdk/python/arvados.html"
+ rm_f "sdk/python/index.html"
rm_rf "sdk/R"
rm_rf "sdk/java-v2/javadoc"
end
@@ -212,5 +214,5 @@ load "zenweb-liquid.rb"
load "zenweb-fix-body.rb"
task :extra_wirings do
- $website.pages["sdk/python/python.html.textile.liquid"].depends_on("sdk/python/arvados/index.html")
+ $website.pages["sdk/python/python.html.textile.liquid"].depends_on("sdk/python/arvados.html")
end
diff --git a/doc/sdk/python/python.html.textile.liquid b/doc/sdk/python/python.html.textile.liquid
index 8ba2dc73e..9fa364c5e 100644
--- a/doc/sdk/python/python.html.textile.liquid
+++ b/doc/sdk/python/python.html.textile.liquid
@@ -12,4 +12,4 @@ Copyright (C) The Arvados Authors. All rights reserved.
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
-notextile. <iframe src="arvados/" style="width:100%; height:100%; border:none" />
+notextile. <iframe src="arvados.html" style="width:100%; height:100%; border:none" />
-----------------------------------------------------------------------
hooks/post-receive
--
More information about the arvados-commits
mailing list