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

@@ -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 = []

docs/index.rst

@@ -0,0 +1,8 @@
+Welcome to kiwix-tools' documentation!
+======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   kiwix-serve

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.
+

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()])

docs/requirements.txt

@@ -0,0 +1,2 @@
+Sphinx==5.3.0
+sphinx-rtd-theme==1.1.1

meson.build

@@ -26,3 +26,6 @@ if static_linkage
 endif
 
 subdir('src')
+if get_option('doc')
+  subdir('docs')
+endif

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.')