mirror of
https://github.com/kiwix/kiwix-tools.git
synced 2025-09-22 19:38:53 -04:00
Merge pull request #586 from kiwix/documentation
This commit is contained in:
Matthieu Gautier
GitHub
commit
4949accdf3
@ -13,6 +13,7 @@ command line tools:
|
|||||||
[&sort=date)](https://hub.docker.com/r/kiwix/kiwix-serve)
|
[&sort=date)](https://hub.docker.com/r/kiwix/kiwix-serve)
|
||||||
[](https://apps.sandstorm.io/app/5uh349d0kky2zp5whrh2znahn27gwha876xze3864n0fu9e5220h)
|
[](https://apps.sandstorm.io/app/5uh349d0kky2zp5whrh2znahn27gwha876xze3864n0fu9e5220h)
|
||||||
[](https://github.com/kiwix/kiwix-tools/actions?query=branch%3Amain)
|
[](https://github.com/kiwix/kiwix-tools/actions?query=branch%3Amain)
|
||||||
|
[](https://kiwix-tools.readthedocs.org/en/latest/?badge=latest)
|
||||||
[](https://www.codefactor.io/repository/github/kiwix/kiwix-tools)
|
[](https://www.codefactor.io/repository/github/kiwix/kiwix-tools)
|
||||||
[](https://www.gnu.org/licenses/gpl-3.0)
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||||
|
|
||||||
|
|||||||
50
docs/conf.py
Normal file
50
docs/conf.py
Normal file
@ -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 = []
|
||||||
8
docs/index.rst
Normal file
8
docs/index.rst
Normal file
@ -0,0 +1,8 @@
|
|||||||
|
Welcome to kiwix-tools' documentation!
|
||||||
|
======================================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
:caption: Contents:
|
||||||
|
|
||||||
|
kiwix-serve
|
||||||
601
docs/kiwix-serve.rst
Normal file
601
docs/kiwix-serve.rst
Normal file
@ -0,0 +1,601 @@
|
|||||||
|
***********
|
||||||
|
kiwix-serve
|
||||||
|
***********
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
``kiwix-serve`` is a tool for serving ZIM file content over HTTP. It supports
|
||||||
|
serving a library containing multiple ZIM files. In a large library served by a
|
||||||
|
``kiwix-serve`` instance clients can look up/filter ZIM files of interest by
|
||||||
|
words in their :term:`titles <ZIM title>` and/or descriptions, language, tags, etc.
|
||||||
|
|
||||||
|
``kiwix-serve`` provides a ZIM file viewer for displaying inidividual pages
|
||||||
|
from a ZIM file inside the user's web browser (without downloading the full ZIM
|
||||||
|
file).
|
||||||
|
|
||||||
|
Clients can also remotely search inside those ZIM files that contain a full-text
|
||||||
|
search database.
|
||||||
|
|
||||||
|
|
||||||
|
Usage
|
||||||
|
=====
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
kiwix-serve --library [OPTIONS] LIBRARY_FILE_PATH
|
||||||
|
kiwix-serve [OPTIONS] ZIM_FILE_PATH ...
|
||||||
|
|
||||||
|
|
||||||
|
Arguments
|
||||||
|
---------
|
||||||
|
|
||||||
|
.. _cli-arg-library-file-path:
|
||||||
|
|
||||||
|
``LIBRARY_FILE_PATH``: path of an XML library file listing ZIM files to serve.
|
||||||
|
To be used only with the :option:`--library` option. Multiple library files can
|
||||||
|
be provided as a semicolon (``;``) separated list.
|
||||||
|
|
||||||
|
``ZIM_FILE_PATH``: ZIM file path (multiple arguments are allowed).
|
||||||
|
|
||||||
|
Options
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. option:: --library
|
||||||
|
|
||||||
|
By default, ``kiwix-serve`` expects a list of ZIM files as command line
|
||||||
|
arguments. Providing the :option:`--library` option tells ``kiwix-serve``
|
||||||
|
that the command line argument is rather a :ref:`library XML file
|
||||||
|
<cli-arg-library-file-path>`.
|
||||||
|
|
||||||
|
.. option:: -i ADDR, --address=ADDR
|
||||||
|
|
||||||
|
Listen only on this IP address. By default the server listens on all
|
||||||
|
available IP addresses.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -p PORT, --port=PORT
|
||||||
|
|
||||||
|
TCP port on which to listen for HTTP requests (default: 80).
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -r ROOT, --urlRootLocation=ROOT
|
||||||
|
|
||||||
|
URL prefix on which the content should be made available (default: empty).
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -d, --daemon
|
||||||
|
|
||||||
|
Detach the HTTP server daemon from the main process.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -a PID, --attachToProcess=PID
|
||||||
|
|
||||||
|
Exit when the process with id PID stops running.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -M, --monitorLibrary
|
||||||
|
|
||||||
|
Monitor the XML library file and reload it automatically when it changes.
|
||||||
|
|
||||||
|
Library reloading can be forced anytime by sending a SIGHUP signal to the
|
||||||
|
``kiwix-serve`` process (this works regardless of the presence of the
|
||||||
|
:option:`--monitorLibrary`/:option:`-M` option).
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -m, --nolibrarybutton
|
||||||
|
|
||||||
|
Disable the library home button in the ZIM viewer toolbar.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -n, --nosearchbar
|
||||||
|
|
||||||
|
Disable the searchbox in the ZIM viewer toolbar.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -b, --blockexternal
|
||||||
|
|
||||||
|
Prevent the users from directly navigating to external resources via such
|
||||||
|
links in ZIM content.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -t N, --threads=N
|
||||||
|
|
||||||
|
Number of threads to run in parallel (default: 4).
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -s N, --searchLimit=N
|
||||||
|
|
||||||
|
Maximum number of ZIM files in a fulltext multizim search (default: No limit).
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -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``.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -c PATH, --customIndex=PATH
|
||||||
|
|
||||||
|
Override the welcome page with a custom HTML file.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -L N, --ipConnectionLimit=N
|
||||||
|
|
||||||
|
Max number of (concurrent) connections per IP (default: infinite,
|
||||||
|
recommended: >= 6).
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -v, --verbose
|
||||||
|
|
||||||
|
Print debug log to STDOUT.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -V, --version
|
||||||
|
|
||||||
|
Print the software version.
|
||||||
|
|
||||||
|
|
||||||
|
.. option:: -h, --help
|
||||||
|
|
||||||
|
Print the help text.
|
||||||
|
|
||||||
|
|
||||||
|
HTTP API
|
||||||
|
========
|
||||||
|
|
||||||
|
``kiwix-serve`` serves content at/under ``http://ADDR:PORT/ROOT`` where
|
||||||
|
``ADDR``, ``PORT`` and ``ROOT`` are the values supplied to the
|
||||||
|
:option:`--address`/:option:`-i`, :option:`--port`/:option:`-p` and
|
||||||
|
:option:`--urlRootLocation`/:option:`-r` options, respectively.
|
||||||
|
|
||||||
|
HTTP API endpoints presented below are relative to that location, i.e.
|
||||||
|
``/foo/bar`` must be actually accessed as ``http://ADDR:PORT/ROOT/foo/bar``.
|
||||||
|
|
||||||
|
.. _welcome-page:
|
||||||
|
|
||||||
|
``/``
|
||||||
|
-----
|
||||||
|
|
||||||
|
Welcome page is served under ``/``. By default this is the library page, where
|
||||||
|
books are listed and can be looked up/filtered interactively. However, the
|
||||||
|
welcome page can be overriden through the :option:`--customIndex`/:option:`-c`
|
||||||
|
command line option of ``kiwix-serve``.
|
||||||
|
|
||||||
|
|
||||||
|
.. _new-opds-api:
|
||||||
|
|
||||||
|
``/catalog/v2`` (OPDS API)
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
The new OPDS API of ``kiwix-serve`` is based on the `OPDS Catalog specification
|
||||||
|
v1.2 <https://specs.opds.io/opds-1.2>`_. All of its endpoints are grouped under
|
||||||
|
``/catalog/v2``.
|
||||||
|
|
||||||
|
:ref:`Legacy OPDS API <legacy-opds-api>` is preserved for backward
|
||||||
|
compatibility.
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/v2/root.xml``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The OPDS Catalog Root links to the OPDS acquisition and navigation feeds
|
||||||
|
accessible through the other endpoints of the OPDS API.
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/v2/searchdescription.xml``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Describes the `/catalog/v2/entries`_ endpoint in `OpenSearch description format
|
||||||
|
<https://developer.mozilla.org/en-US/docs/Web/OpenSearch>`_.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/v2/categories``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Returns the full list of ZIM file categories as an `OPDS Navigation Feed
|
||||||
|
<https://specs.opds.io/opds-1.2#22-navigation-feeds>`_.
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/v2/entries``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Returns the full or filtered list of ZIM files as an `OPDS acquisition feed
|
||||||
|
<https://specs.opds.io/opds-1.2#23-acquisition-feeds>`_ with `complete entries
|
||||||
|
<https://specs.opds.io/opds-1.2#512-partial-and-complete-catalog-entries>`_.
|
||||||
|
|
||||||
|
By default, all entries in the library are returned. A subset can be requested
|
||||||
|
by providing one or more filtering criteria, whereupon only entries matching
|
||||||
|
*all* of the criteria are included in the response. The filtering criteria must
|
||||||
|
be specified as URL search parameters.
|
||||||
|
|
||||||
|
* ``lang`` - filter by language (specified as a 3-letter language code).
|
||||||
|
|
||||||
|
* ``category`` - filter by categories associated with the library entries.
|
||||||
|
|
||||||
|
* ``tag`` - filter by tags associated with the library entries. Multiple tags
|
||||||
|
can be provided as a semicolon separated list (e.g
|
||||||
|
``tag=wikipedia;_videos:no``). The result will contain only those entries
|
||||||
|
that contain *all* of the requested tags.
|
||||||
|
|
||||||
|
* ``notag`` - filter out (exclude) entries with *any* of the specified tags
|
||||||
|
(example - ``notag=ted;youtube``).
|
||||||
|
|
||||||
|
* ``maxsize`` - include in the results only entries whose size (in bytes)
|
||||||
|
doesn't exceed the provided value.
|
||||||
|
|
||||||
|
* ``q`` - include in the results only entries that contain the specified text
|
||||||
|
in the title or description.
|
||||||
|
|
||||||
|
* ``name`` - include in the results only the entry with the specified
|
||||||
|
:term:`name <ZIM name>`.
|
||||||
|
|
||||||
|
* ``start=s`` and ``count=n`` - these parameters enable pagination of the
|
||||||
|
search/filtering results - the feed will contain (at most) ``n`` results
|
||||||
|
starting from the result # ``s`` (0-based).
|
||||||
|
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
|
||||||
|
.. code:: sh
|
||||||
|
|
||||||
|
# List only books in Italian (lang=ita) but
|
||||||
|
# return only results ## 100-149 (start=100&count=50)
|
||||||
|
$ curl 'http://localhost:8080/catalog/v2/entries?lang=ita&start=100&count=50'
|
||||||
|
|
||||||
|
# List only books with category of 'wikipedia' AND containing the word
|
||||||
|
# 'science' in the title or description
|
||||||
|
$ curl 'http://localhost:8080/catalog/v2/entries?q=science&category=wikipedia'
|
||||||
|
|
||||||
|
``/catalog/v2/entry/ZIMID``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Returns full info about the library entry with :term:`UUID <ZIM UUID>`
|
||||||
|
``ZIMID``.
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/v2/illustration/ZIMID``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
``/catalog/v2/illustration/ZIMID?size=N``
|
||||||
|
|
||||||
|
Returns the illustration of size ``NxN`` pixels for the library entry with
|
||||||
|
:term:`UUID <ZIM UUID>` ``ZIMID``.
|
||||||
|
|
||||||
|
If no illustration of requested size is found a HTTP 404 error is returned.
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/v2/languages``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Returns the full list of ZIM file languages as an `OPDS Navigation Feed
|
||||||
|
<https://specs.opds.io/opds-1.2#22-navigation-feeds>`_.
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/v2/partial_entries``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Returns the full or filtered list of ZIM files as an `OPDS acquisition feed
|
||||||
|
<https://specs.opds.io/opds-1.2#23-acquisition-feeds>`_ with `partial entries
|
||||||
|
<https://specs.opds.io/opds-1.2#512-partial-and-complete-catalog-entries>`_.
|
||||||
|
|
||||||
|
Supported filters are the same as for the `/catalog/v2/entries`_ endpoint.
|
||||||
|
|
||||||
|
|
||||||
|
.. _legacy-opds-api:
|
||||||
|
|
||||||
|
``/catalog`` (Legacy OPDS API)
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
The legacy OPDS API is preserved for backward compatibility and is deprecated.
|
||||||
|
:ref:`New OPDS API <new-opds-api>` should be used instead.
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/root.xml``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Full library OPDS catalog (list of all ZIM files).
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/searchdescription.xml``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Describes the `/catalog/search`_ endpoint in `OpenSearch description format
|
||||||
|
<https://developer.mozilla.org/en-US/docs/Web/OpenSearch>`_.
|
||||||
|
|
||||||
|
|
||||||
|
``/catalog/search``
|
||||||
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Returns the list of ZIM files (in OPDS catalog format) matching the
|
||||||
|
search/filtering criteria. Supported filters are the same as for the
|
||||||
|
`/catalog/v2/entries`_ endpoint.
|
||||||
|
|
||||||
|
|
||||||
|
``/catch/external``
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
``/catch/external?source=URL``
|
||||||
|
|
||||||
|
Generates a HTML page with a link leading to (the decoded version of) ``URL``
|
||||||
|
and a warning that following that link will load an external (out of ZIM)
|
||||||
|
resource.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
``source``: URL of the external resource (must be URL-encoded).
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
.. code:: sh
|
||||||
|
|
||||||
|
# Intercept an external link to https://example.com?query=abcd
|
||||||
|
$ curl 'http://localhost:8080/catch/external?source=https%3A%2F%2Fexample.com%3Fquery%3Dabcd'
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
``/content``
|
||||||
|
------------
|
||||||
|
|
||||||
|
ZIM file content is served under the ``/content`` endpoint as described below.
|
||||||
|
|
||||||
|
|
||||||
|
``/content/ZIMNAME/PATH/IN/ZIMFILE``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Returns the entry with path ``PATH/IN/ZIMFILE`` from ZIM file with :term:`name
|
||||||
|
<ZIM name>` ``ZIMNAME``.
|
||||||
|
|
||||||
|
|
||||||
|
``/content/ZIMNAME``
|
||||||
|
^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
``/content/ZIMNAME`` redirects to the main page of the ZIM file with :term:`name
|
||||||
|
<ZIM name>` ``ZIMNAME`` (unless that ZIM file contains an entry with an empty
|
||||||
|
path or path equal to ``/``, in which case that entry is returned).
|
||||||
|
|
||||||
|
|
||||||
|
``/random``
|
||||||
|
-----------
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
``/random?content=ZIMNAME``
|
||||||
|
|
||||||
|
Generates a HTTP redirect to a randomly selected article/page from the
|
||||||
|
specified ZIM file.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
``content``: :term:`name <ZIM name>` of the ZIM file.
|
||||||
|
|
||||||
|
|
||||||
|
``/raw/ZIMNAME/content/PATH/IN/ZIMFILE``
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
|
Returns the entry with path ``PATH/IN/ZIMFILE`` from the ZIM file with
|
||||||
|
:term:`name <ZIM name>` ``ZIMNAME``. Currently, this endpoint almost duplicates
|
||||||
|
(with some subtle technical differences) the newer endpoint
|
||||||
|
`/content/ZIMNAME/PATH/IN/ZIMFILE`_. The important difference is that the
|
||||||
|
``/raw`` endpoint guarantees that no server-side processing will be applied to
|
||||||
|
the returned content, whereas content obtained via the ``/content`` endpoint
|
||||||
|
may in the future undergo some processing intended to improve the operation of
|
||||||
|
the viewer (e.g. compensating for certain bugs in ZIM creation).
|
||||||
|
|
||||||
|
|
||||||
|
``/raw/ZIMNAME/meta/METADATAID``
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
Returns the metadata item ``METADATAID`` from the ZIM file with :term:`name
|
||||||
|
<ZIM name>` ``ZIMNAME``.
|
||||||
|
|
||||||
|
|
||||||
|
``/search``
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Performs a full text search on one or more ZIM files and returns an HTML page
|
||||||
|
with a list of links to matching pages along with snippets of the matching
|
||||||
|
portions of those pages.
|
||||||
|
|
||||||
|
.. _multi-zim-search-constraints:
|
||||||
|
|
||||||
|
A multi-ZIM search request must comply with the following constraints:
|
||||||
|
|
||||||
|
* the number of ZIM files participating in the search operation must not exceed
|
||||||
|
the limit imposed by the :option:`--searchLimit` option of ``kiwix-serve``.
|
||||||
|
|
||||||
|
* all of the ZIM files participating in the same search operation must be in
|
||||||
|
the same language.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
|
||||||
|
ZIM file selection parameters:
|
||||||
|
|
||||||
|
At least one of the following parameters must be provided in order to
|
||||||
|
specify in which ZIM file(s) to search. Parameters appearing earlier in
|
||||||
|
below list take precedence over subsequent ones (the later ones, even if
|
||||||
|
present in the request, are simply ignored).
|
||||||
|
|
||||||
|
``content``: :term:`name <ZIM name>` of the ZIM file (for a single-ZIM
|
||||||
|
search). This is a legacy parameter. ``books.name`` should be used instead.
|
||||||
|
|
||||||
|
``books.id``: :term:`UUID <ZIM UUID>` of the ZIM file. Can be repeated for
|
||||||
|
a multi-ZIM search, however must respect the :ref:`multi-ZIM search
|
||||||
|
constraints <multi-zim-search-constraints>`.
|
||||||
|
|
||||||
|
``books.name``: :term:`name <ZIM name>` of the ZIM file. Can be repeated
|
||||||
|
for a multi-ZIM search, however must respect the :ref:`multi-ZIM search
|
||||||
|
constraints <multi-zim-search-constraints>`.
|
||||||
|
|
||||||
|
Query parameters:
|
||||||
|
|
||||||
|
``pattern`` (optional; defaults to an empty string): text to search for.
|
||||||
|
|
||||||
|
``latitude``, ``longitude`` & ``distance`` (optional): geospatial query
|
||||||
|
parameters. If all of these are provided, then the results will be
|
||||||
|
restricted to geotagged pages that are within ``distance`` metres from the
|
||||||
|
location on Earth with coordinates ``latitude`` and ``longitude``.
|
||||||
|
|
||||||
|
Pagination parameters:
|
||||||
|
|
||||||
|
``pageLength`` (optional, default: 25): maximum number of search results in
|
||||||
|
the response. Capped at 140.
|
||||||
|
|
||||||
|
``start`` (optional, default: 1): this parameter enables pagination of
|
||||||
|
results. The response will include up to ``pageLength`` results starting
|
||||||
|
with entry # ``start`` from the full list of search results (the first
|
||||||
|
result is assumed to have index 1).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
``/search/searchdescription.xml``
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
Describes the `/search`_ endpoint in `OpenSearch description format
|
||||||
|
<https://developer.mozilla.org/en-US/docs/Web/OpenSearch>`_.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
``/skin``
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Static front-end resources (such as CSS, javascript and images) are all grouped
|
||||||
|
under ``/skin``.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
``/skin/PATH/TO/RESOURCE[?cacheid=CACHEID]``
|
||||||
|
|
||||||
|
`Cache busting
|
||||||
|
<https://javascript.plainenglish.io/what-is-cache-busting-55366b3ac022>`_ of
|
||||||
|
static resources is supported via the optional param ``cacheid``. By default,
|
||||||
|
i.e. when the ``cacheid`` parameter is not specified while accessing the
|
||||||
|
``/skin`` endpoint, static resources are served as if they were dynamic (i.e.
|
||||||
|
could be different for an immediately repeated request). Specifying the
|
||||||
|
``cacheid`` parameter with a correct value (matching the value embedded in the
|
||||||
|
``kiwix-serve`` instance), makes the returned resource to be presented as
|
||||||
|
immutable. However, if the value of the ``cacheid`` parameter mismatches then
|
||||||
|
``kiwix-serve`` responds with a 404 HTTP error.
|
||||||
|
|
||||||
|
``kiwix-serve``'s default front-end (the :ref:`welcome page <welcome-page>` and
|
||||||
|
the :ref:`ZIM file viewer <zim-file-viewer>`) access all underlying static
|
||||||
|
resources by using explicit ``cacheid`` s.
|
||||||
|
|
||||||
|
|
||||||
|
``/suggest``
|
||||||
|
------------
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
``/suggest?content=ZIMNAME[&term=QUERY][&count=N][&start=S]``
|
||||||
|
|
||||||
|
Returns suggestions (in JSON format) for a text string that is assumed to be a
|
||||||
|
partially typed search for a page inside a particular ZIM file.
|
||||||
|
|
||||||
|
Suggestions are obtained as matches of the query text against the page titles
|
||||||
|
in the ZIM file using the title index database generated during the creation of
|
||||||
|
the ZIM file.
|
||||||
|
|
||||||
|
In case of a multi-word query the order of the words matters in two ways:
|
||||||
|
|
||||||
|
1. the last word is considered as partially typed, unless followed by a space;
|
||||||
|
2. ranking of the matches.
|
||||||
|
|
||||||
|
If the ZIM file doesn't contain a title index then suggestions are generated by
|
||||||
|
listing page titles starting *exactly* (in a case sensitive manner) with the
|
||||||
|
query text. Otherwise, suggestions are case-insensitive.
|
||||||
|
|
||||||
|
If the ZIM file contains a full text search index, then an extra suggestion is
|
||||||
|
added as an option to perform a full text search in the said ZIM file.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
``content`` (mandatory): :term:`name <ZIM name>` of the ZIM file.
|
||||||
|
|
||||||
|
``term`` (optional; defaults to an empty string): query text.
|
||||||
|
|
||||||
|
``count`` (optional, default: 10): maximum number of page suggestions in the
|
||||||
|
response (i.e. the extra option to perform a full text search is not included
|
||||||
|
in this count).
|
||||||
|
|
||||||
|
``start`` (optional, default: 0): this parameter enables pagination of
|
||||||
|
results. The response will include up to ``count`` entries starting with
|
||||||
|
entry # ``start`` from the full list of page suggestions (the first result is
|
||||||
|
assumed to have index 0).
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
.. code:: sh
|
||||||
|
|
||||||
|
$ curl 'http://localhost/suggest?content=stackoverflow_en&term=pyth&count=50'
|
||||||
|
|
||||||
|
|
||||||
|
.. _zim-file-viewer:
|
||||||
|
|
||||||
|
``/viewer``
|
||||||
|
-----------
|
||||||
|
|
||||||
|
ZIM file viewer. The ZIM file and entry therein must be specified via the hash
|
||||||
|
component of the URL as ``/viewer#ZIMNAME/PATH/IN/ZIMFILE``.
|
||||||
|
|
||||||
|
|
||||||
|
``/viewer_settings.js``
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
Settings of the ZIM file viewer that are configurable via certain command line
|
||||||
|
options of ``kiwix-serve`` (e.g. ``--nolibrarybutton``).
|
||||||
|
|
||||||
|
|
||||||
|
/ANYTHING/ELSE
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Any other URL is considered as an attempt to access ZIM file content using the
|
||||||
|
legacy URL scheme and is redirected to ``/content/ANYTHING/ELSE``.
|
||||||
|
|
||||||
|
|
||||||
|
Glossary
|
||||||
|
========
|
||||||
|
|
||||||
|
.. glossary::
|
||||||
|
|
||||||
|
ZIM filename
|
||||||
|
|
||||||
|
Name of a ZIM file on the server filesystem.
|
||||||
|
|
||||||
|
ZIM name
|
||||||
|
|
||||||
|
Identifier of a ZIM file in the server's library (used for referring to a
|
||||||
|
particular ZIM file in requests).
|
||||||
|
|
||||||
|
For a ``kiwix-serve`` started with a list of ZIM files, ZIM names are
|
||||||
|
derived from the filename by dropping the extension and replacing certain
|
||||||
|
characters (spaces are replaced with underscores, and ``+`` symbols are
|
||||||
|
replaced with the text ``plus``). Presence of the
|
||||||
|
:option:`-z`/:option:`--nodatealiases` option will create additional names
|
||||||
|
(aliases) for filenames with dates.
|
||||||
|
|
||||||
|
For a ``kiwix-serve`` started with the :option:`--library` option, ZIM
|
||||||
|
names come from the library XML file.
|
||||||
|
|
||||||
|
ZIM names are expected to be unique across the library. Any name conflicts
|
||||||
|
(including those caused by the usage of the
|
||||||
|
:option:`-z`/:option:`--nodatealiases` option) are reported on STDERR but,
|
||||||
|
otherwise, are ignored.
|
||||||
|
|
||||||
|
ZIM title
|
||||||
|
|
||||||
|
Title of a ZIM file. This can be any text (with whitespace). It is never
|
||||||
|
used as a way of referring to a ZIM file.
|
||||||
|
|
||||||
|
ZIM UUID
|
||||||
|
|
||||||
|
This is a unique identifier of a ZIM file designated at its creation time
|
||||||
|
and embedded in the ZIM file. Certain ``kiwix-serve`` operations may
|
||||||
|
require that a ZIM file be referenced through its UUID rather than name.
|
||||||
7
docs/meson.build
Normal file
7
docs/meson.build
Normal file
@ -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()])
|
||||||
2
docs/requirements.txt
Normal file
2
docs/requirements.txt
Normal file
@ -0,0 +1,2 @@
|
|||||||
|
Sphinx==5.3.0
|
||||||
|
sphinx-rtd-theme==1.1.1
|
||||||
@ -26,3 +26,6 @@ if static_linkage
|
|||||||
endif
|
endif
|
||||||
|
|
||||||
subdir('src')
|
subdir('src')
|
||||||
|
if get_option('doc')
|
||||||
|
subdir('docs')
|
||||||
|
endif
|
||||||
|
|||||||
@ -1,2 +1,4 @@
|
|||||||
option('static-linkage', type : 'boolean', value : false,
|
option('static-linkage', type : 'boolean', value : false,
|
||||||
description : 'Create statically linked binaries.')
|
description : 'Create statically linked binaries.')
|
||||||
|
option('doc', type : 'boolean', value : false,
|
||||||
|
description : 'Build the documentations.')
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user