From 6957a8cb1e9338a4ee367a952b26090024a9c115 Mon Sep 17 00:00:00 2001 From: Veloman Yunkan Date: Wed, 7 Dec 2022 17:16:17 +0400 Subject: [PATCH] Enter docs/ This commit introduces an embryo of sphinx-based documentation. The content of documentation in this commit is limited to the command line options of kiwix-serve. --- docs/conf.py | 50 ++++++++++++++++++ docs/index.rst | 8 +++ docs/kiwix-serve.rst | 114 ++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 7 +++ docs/requirements.txt | 2 + meson.build | 3 ++ meson_options.txt | 2 + 7 files changed, 186 insertions(+) create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/kiwix-serve.rst create mode 100644 docs/meson.build create mode 100644 docs/requirements.txt diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..bb81550 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,50 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'kiwix-tools' +copyright = '2022, kiwix-team' +author = 'kiwix-team' + + +# -- General configuration --------------------------------------------------- + +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +if not on_rtd: + html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..a4076af --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,8 @@ +Welcome to kiwix-tools' documentation! +====================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + kiwix-serve diff --git a/docs/kiwix-serve.rst b/docs/kiwix-serve.rst new file mode 100644 index 0000000..1227619 --- /dev/null +++ b/docs/kiwix-serve.rst @@ -0,0 +1,114 @@ +*********** +kiwix-serve +*********** + +Usage +===== + +.. code-block:: sh + + kiwix-serve --library [OPTIONS] LIBRARY_FILE_PATH + kiwix-serve [OPTIONS] ZIM_FILE_PATH ... + + +Mandatory arguments +------------------- + +``LIBRARY_FILE_PATH``: XML library file path listing ZIM file to serve. To be +used only with the ``--library`` option. + +``ZIM_FILE_PATH``: ZIM file path (multiple arguments are allowed). + +Options +------- + +-i ADDR, --address=ADDR + + Listen only on this IP address. By default the server listens on all + available IP addresses. + + +-p PORT, --port=PORT + + TCP port on which to listen for HTTP requests (default: 80). + + +-r ROOT, --urlRootLocation=ROOT + + URL prefix on which the content should be made available (default: /). + + +-d, --daemon + + Detach the HTTP server daemon from the main process. + + +-a PID, --attachToProcess=PID + + Exit when the process with id PID stops running. + + +-M, --monitorLibrary + + Monitor the XML library file and reload it automatically when it changes. + + +-m, --nolibrarybutton + + Disable the library home button in the ZIM viewer toolbar. + + +-n, --nosearchbar + + Disable the searchbox in the ZIM viewer toolbar. + + +-b, --blockexternal + + Prevent the users from directly navigating to external resources via such + links in ZIM content. + + +-t N, --threads=N + + Number of threads to run in parallel (default: 4). + + +-s N, --searchLimit=N + + Maximum number of ZIM files in a fulltext multizim search (default: No limit). + + +-z, --nodatealiases + + Create URL aliases for each content by removing the date embedded in the file + name. The expected format of the date in the filename is ``_YYYY-MM``. For + example, ZIM file ``wikipedia_en_all_2020-08.zim`` will be accessible both as + ``wikipedia_en_all_2020-08`` and ``wikipedia_en_all``. + + +-c PATH, --customIndex=PATH + + Override the welcome page with a custom HTML file. + + +-L N, --ipConnectionLimit=N + + Max number of (concurrent) connections per IP (default: infinite, + recommended: >= 6). + + +-v, --verbose + + Print debug log to STDOUT. + + +-V, --version + + Print the software version. + + +-h, --help + + Print the help text. + diff --git a/docs/meson.build b/docs/meson.build new file mode 100644 index 0000000..71d4fc5 --- /dev/null +++ b/docs/meson.build @@ -0,0 +1,7 @@ + +sphinx = find_program('sphinx-build', native:true) + +sphinx_target = run_target('doc', + command: [sphinx, '-bhtml', + meson.current_source_dir(), + meson.current_build_dir()]) diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..24bbc56 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +Sphinx==5.3.0 +sphinx-rtd-theme==1.1.1 diff --git a/meson.build b/meson.build index 0c7baaa..bab9221 100644 --- a/meson.build +++ b/meson.build @@ -26,3 +26,6 @@ if static_linkage endif subdir('src') +if get_option('doc') + subdir('docs') +endif diff --git a/meson_options.txt b/meson_options.txt index 3b0daed..04d2079 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -1,2 +1,4 @@ option('static-linkage', type : 'boolean', value : false, description : 'Create statically linked binaries.') +option('doc', type : 'boolean', value : false, + description : 'Build the documentations.')