so we don't need to use virtualenv python package for creating a
virtualenv, the "venv" module in Python3 would suffice.
see also https://docs.python.org/3/library/venv.html
Signed-off-by: Kefu Chai <kchai@redhat.com>
otherwise livehtml uses the default html builder. so we can copy and
paste the partial URL to cross check the rendering result.
Signed-off-by: Kefu Chai <kchai@redhat.com>
Downside is you have to delete and re-run if the deps change. The venv
install is suuuuper slow for me, though, so this is a win.
Signed-off-by: Sage Weil <sage@newdream.net>
so we can build the command doc using ReadTheDoc infra, without adding
the generated rst file to the source repo.
before this change, all the commands are ordered alphabetically. after
this change, command docs are generated by two directives, and are
ordered separately. we could restructure the directives and merge them.
but let's leave it for a future change if this is important.
for more details on writing sphinx directives, see
https://www.sphinx-doc.org/en/master/extdev/markupapi.html and
https://docutils.sourceforge.io/docs/howto/rst-directives.html
Signed-off-by: Kefu Chai <kchai@redhat.com>
per Radoslow Zarzynski, the build failure was due to missing Python.h
for the python version he was using on the system.
This reverts commit bc73204812.
Signed-off-by: Kefu Chai <kchai@redhat.com>
to silence the warning of
WARNING: --use-feature=2020-resolver no longer has any effect, since it is now the default dependency resolver in pip. This will become an error in pip 21.0.
Signed-off-by: Kefu Chai <kchai@redhat.com>
since all the python bindings are required for building the doc, extract
them into admin/doc-pybind.txt.
because the pybind python extensions require Cython python module to build,
we have to move them into another requirement file, and install them after
Cython is installed.
Signed-off-by: Kefu Chai <kchai@redhat.com>
it is time-consuming to rebuild the python bindings every time we
rebuild the document, it'd be ideal if we could just build document.
in this change, in addition to "html" and "doc", "livehtml" argument is
now supported by build-doc script, so one can just use
./build-doc livehtml
to build and start a web server. whenever a change in doc/ is detected,
the document is rebuilt. for more details, see
https://pypi.org/project/sphinx-autobuild/
Signed-off-by: Kefu Chai <kchai@redhat.com>
to silence the warning like
follow the suggestion from pip
ERROR: After October 2020 you may experience errors when installing or updating packages. This is because pip will change the way that it resolves dependency conflicts.
We recommend you use --use-feature=2020-resolver to test your packages with the new resolver before it becomes the default.
Fixes: https://tracker.ceph.com/issues/47636
Signed-off-by: Kefu Chai <kchai@redhat.com>
to address the build failure of
python -m pip install --exists-action=w --no-cache-dir -r admin/doc-requirements.txt
ERROR: ../src/python-common is not a valid editable requirement. It should either be a path to a local project or a VCS URL (beginning with svn+, git+, hg+, or bzr+).
Signed-off-by: Kefu Chai <kchai@redhat.com>
as compilers targeting ELF does not add the leading "_" to symbol names,
while clang on OSX always do this.
and remove the underscore from the symbol name when generating the
function name, as the compiler will add it back for us.
Signed-off-by: Kefu Chai <kchai@redhat.com>
which is not supported by ld on OSX.
also, pass the rpath argument as a new command line argument instead
using -rpath=foo, which is not supported by llvm linker.
Signed-off-by: Kefu Chai <kchai@redhat.com>
we should not `set -e` at the very beginning of this script, which fails
the script if any dependency is missing without printing out error
messages.
in this change `set -e` is removed. and refactor the code to print the
error message.
Signed-off-by: Kefu Chai <kchai@redhat.com>
since we've dropped the support of python36-*, i.e. python packages
provided by EPEL7 before RHEL7/CentOS7 included python3. as before the
inclusion of python3 as supported python3, python packages are named
python36-*. and they don't provide python3-*. so we had to install
python36-* explicitly. now that we are able to use the python3-*
packages, we can just install python3-*.
Signed-off-by: Kefu Chai <kchai@redhat.com>
Don't use site-packages, since the host might have the same version, and
it won't have the ditaa and breathe.
Require Cython to make the venv sufficient.
Signed-off-by: Sage Weil <sage@redhat.com>
to address https://github.com/sphinx-doc/sphinx/issues/3620, we need to
use sphinx with its fix at
e049f86b2d
in other words, we need to use sphinx v2.0.0 and up. but sphinx 2.0
requires python >= 3.5, so we have to use python3 for building the
documents.
in this change:
* doc-requirements.txt: install python3 packages on debian derivatives
* build-doc: install python3.6 packages from EPEL7, and use python3
venv for using sphinx2
* doc-requirements.txt: bump up all python packages to latest
stable.
Signed-off-by: Kefu Chai <kchai@redhat.com>
This allows the build to fail, but also report a list of warnings so that
multiple runs are not required to find all the errors in doc changes
Signed-off-by: Abhishek Lekshmanan <abhishek@suse.com>
Png images included into docs are useless because of small resolution.
http://docs.ceph.com/docs/master/dev/peering/#state-model
While SVG is vector and supported by Sphinx.
Signed-off-by: Aleksei Gutikov <aleksey.gutikov@synesis.ru>
If you have python ceph bindings installed on your system, the doc-build
script will fail since pip detects them and fails to install the updated
bindings in the virtualenv. This fixes the issue by adding --upgrade
flag to pip so that it overrides the system-installed libraries.
Signed-off-by: Boris Ranto <branto@redhat.com>
In document, it is called 'libxml2-devel', one of the dependent
package of CentOS/RHEL7. But the 'build-doc' check 'libxml-devel'.
And it id also called 'libxml2-devel' in software of yum repo .
So correct the checked package name in ceph/admin/build-doc.
Signed-off-by: Yu Shengzuo <yu.shengzuo@99cloud.net>
currently this works fine, but we ran into this problem before. and
technically "-iquote<dir>" is the valid syntax, and "-iquote <dir>"
is not. see https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html
Signed-off-by: Kefu Chai <kchai@redhat.com>
the empty .so file does not compile at all, so we need to bypass the
sanity check, if we are building docs. and what sphinx needs is just the
docstrings.
Fixes: http://tracker.ceph.com/issues/16940
Signed-off-by: Kefu Chai <kchai@redhat.com>
