this is a follow-up of 1debd98565,
we should use the logging from sphinx.util instead from Python standard
library's logging.
Signed-off-by: Kefu Chai <kchai@redhat.com>
it prints out
skipping non-JSON example generation.
if an API does not contains example while ":example:" is specified for
openapi extension, and if this API is not a GET request, openapi
extention complains.
see also
9dbae9c9a6/sphinxcontrib/openapi/openapi30.py (L191)
Signed-off-by: Kefu Chai <kchai@redhat.com>
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>
since we are able to build the python bindings using the stub
implementation of C binding, let's enable the API docs build.
Signed-off-by: Kefu Chai <kchai@redhat.com>
if $release is "dev", then the release being built is not a stable
version.
drop ceph.js, as the web page is generated at build time.
since the last user of "releases.json" is gone, now we can
drop the hooks preparing "releases.json" in conf.py as well.
Signed-off-by: Kefu Chai <kchai@redhat.com>
check if the release being built is EOL when building the document, so
no need to use javascript to read releases.json anymore.
Signed-off-by: Kefu Chai <kchai@redhat.com>
instead of hardwiring the "|stable-release|" to "octopus" use the latest
release name found in 'doc/releases/releases.yml'
Signed-off-by: Kefu Chai <kchai@redhat.com>
this change silences flake8 warnings like:
expected 2 blank lines after class or function definition, found 1
[E305]
Signed-off-by: Kefu Chai <kchai@redhat.com>
"tags" is exposed by sphinx, so we will have access to this variable
when sphinx imports this file. this silences the warning from flake8:
undefined name 'tags' [F821]
Signed-off-by: Kefu Chai <kchai@redhat.com>
"luminous" is a magic number in these contexts, and we should use a
constant for representing it.
the "sphinx_substitution_extensions" sphinx extension is introduced for
performing the global subsitution.
Signed-off-by: Kefu Chai <kchai@redhat.com>
otherwise we could have following errors:
Invalid C declaration: Expected identifier in nested name, got keyword: int [error at 18]
CEPH_RADOS_API int rados_aio_append (rados_ioctx_t io, const char *oid, rados_completion_t completion, const char *buf, size_t len)
------------------^
Signed-off-by: Kefu Chai <kchai@redhat.com>
to address following warning:
jenkins-build/build/workspace/ceph-pr-docs/doc/conf.py:102: RemovedInSphinx40Warning: The app.add_javascript() is deprecated. Please use app.add_js_file() instead.
Signed-off-by: Kefu Chai <kchai@redhat.com>
RTD does not support installing system packages, the only ways to install
dependencies are setuptools and pip. while ditaa is a tool written in
Java. so we need to find a native python tool allowing us to render ditaa
images. plantweb is able to the web service for rendering the ditaa
diagram. so let's use it as a fallback if "ditaa" is not around.
also start a new line after the directive, otherwise planweb server will
return 500 at seeing the diagram.
Signed-off-by: Kefu Chai <kchai@redhat.com>
because it'd difficult to prepare (dummy) librados,libcephfs and librbd for
their python bindings in the building environment offered by Read the Docs.
Signed-off-by: Kefu Chai <kchai@redhat.com>
by default, the user agent's css sets `margin-block-end` of "ul ul" to
"0", which renders the unordered lists in release notes cluttered. as we
are using nested unordered list to present the changes in different
components.
in this change a customized css is added to reset the begin and end
margin of ul to 1em, which is the default value of top level ul.
Signed-off-by: Kefu Chai <kchai@redhat.com>
This reverts commit 88d6d499e0.
All doc builds are currently broken due to this change since
the HTML files are written without the necessary ".html"
extension.
Signed-off-by: Jason Dillaman <dillaman@redhat.com>
since sphinx 1.5, SOURCELINK_SUFFIX is always added to the source file,
and search page always tries to add it to the highlighted source result.
Signed-off-by: Kefu Chai <kchai@redhat.com>
Add '*.inc.rst' to the list of excluded patterns from sphinx-build. This
allows for using '*.inc.rst' as includes, and avoids duplicates. The
benefit of keeping the trailing '.rst' extension is that most IDEs use
that to render reStructured Text files.
Fixes: http://tracker.ceph.com/issues/37530
Signed-off-by: Ernesto Puerta <epuertat@redhat.com>
The license applicable to the files under doc/ was originally declared (in the
top-level file COPYING) to be "Creative Commons Attribution-ShareAlike (CC
BY-SA)" by ed0653b493
This license declaration omitted a version number.
Some time later ef7418421b was merged, mentioning
CC-BY-SA-1.0 as one of the Ceph source code licenses. Although the purpose of that
commit was only to summarize the canonical license information from COPYING, it
unintentionally became the only place in the source code where the doc license
version was specified.
In March 2018, the Debian project warned that CC-BY-SA-1.0 does not meet its
criteria for inclusion in the "free" section of the Debian distribution. (For
that, at least version 3.0 must be used.)
This new commit removes the doc license ambiguity by setting it to CC-BY-SA-3.0
in all places where the license is mentioned.
The exact spelling of the license name is taken from https://spdx.org/licenses/
Fixes: http://tracker.ceph.com/issues/23336
Signed-off-by: Nathan Cutler <ncutler@suse.com>
it works with setuptools and is now compatible with py3
the py3 branch is created to track the upstream's master branch
Signed-off-by: Kefu Chai <kchai@redhat.com>
because it's deprecated, and is on by default in the specified sphinx
version (v1.6.3):
this change silences following warning:
build-doc/virtualenv/local/lib/python2.7/site-packages/sphinx/environment/__init__.py:683:
RemovedInSphinx17Warning: html_use_smartypants option is deprecated.
Smart quotes are on by default; if you want to disable or customize
them, use the smart_quotes option in docutils.conf.
RemovedInSphinx17Warning)
Signed-off-by: Kefu Chai <kchai@redhat.com>
so it can render the doxygen generated objects with the proper domain by
checking the extension of rendered source file.
Signed-off-by: Kefu Chai <kchai@redhat.com>
