breathe calls doxygen for extracting/generating docs from code.
while doxygen complains at seeing undocumented fields/func. these
warnings could fail the sphinx-build command, if it takes warnings
as errors.
in this change, these warnings are silenced.
Signed-off-by: Kefu Chai <tchaikov@gmail.com>
Workaround rgw modules conflict, as there are two separate modules named
rgw: src/pybind/rgw, src/pybind/mgr/rgw
Signed-off-by: Yehuda Sadeh <yehuda@redhat.com>
for rendering sequence-diagram. unlike ditaa, seqdiag allows us to
create sequence-diagram without worrying about the layout. and the
syntax is quite like that of dot.
Signed-off-by: Kefu Chai <kchai@redhat.com>
just in case, otherwise we could have
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/42577/lib/python3.8/site-packages/sphinxcontrib/ditaa.py", line 200, in html_visit_ditaa
render_ditaa_html(self, node, node['code'], node['options'])
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/42577/lib/python3.8/site-packages/sphinxcontrib/ditaa.py", line 177, in render_ditaa_html
fname, outfn = render_ditaa(self, code, options, prefix)
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/42577/lib/python3.8/site-packages/sphinxcontrib/ditaa.py", line 141, in render_ditaa
p = Popen(ditaa_args, stdout=PIPE, stdin=PIPE, stderr=PIPE)
File "/home/docs/.pyenv/versions/3.8.6/lib/python3.8/subprocess.py", line 854, in __init__
self._execute_child(args, executable, preexec_fn, close_fds,
File "/home/docs/.pyenv/versions/3.8.6/lib/python3.8/subprocess.py", line 1702, in _execute_child
raise child_exception_type(errno_num, err_msg, err_filename)
OSError: [Errno 8] Exec format error: '/usr/bin/ditaa'
Signed-off-by: Kefu Chai <kchai@redhat.com>
prepare for the change to split the options by services
in future, osd will have its own osd.yaml.in, while crimson will consume
both osd.yaml.in and crimson.yaml.in.
Signed-off-by: Kefu Chai <kchai@redhat.com>
* add a field named "fmt_desc", which is the description formatted using
reStructuredText. it is preserved as it is if it's different from the
desc or long_desc of an option. we can consolidate it with long_desc
in future, and use pretty printer which has minimal support for
reStructuredText for printing the formatted descriptions for a better
user experience of command line. but at this moment, fmt_desc has
only one consumer: the "ceph_confval" sphinx extension which extracts
and translate the options yaml file to reStructuredText, which is in
turn rendered by sphinx.
* remove unused options from the doc
- journal_queue_max_ops
- journal_queue_max_bytes
Signed-off-by: Kefu Chai <kchai@redhat.com>
* move the breadcrumbs to the top
* add border around admonition elements
* use different colors and fonts for section headers
* add decoration lines at the bottom of breadcrumbs
* remove left and right borders in tables
* override the injected versions, the name of theme
is different from "sphinx_rtd_theme", but the
versions element is still displayed at the
bottom-left corner as "versions.html" defines.
without overriding .rst-badge CSS styling,
readthedocs puts the injected versions at
the default bottom-right corner, see
2a519f1146/readthedocs/api/v2/templates/restapi/footer.html
Signed-off-by: Kefu Chai <kchai@redhat.com>
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>
Leonid Usov
Kefu Chai
Salar Nosrati-Ershad
Josh Durgin
Yehuda Sadeh
Kefu Chai
Courtney Caldwell
Sebastian Wagner
Jason Dillaman
Brad Hubbard