Doc improvement

Author: hanke0

ctools/__init__.pyi

@@ -137,7 +137,7 @@ class Channel:
 
 
 class SortedMap:
-    def __init__(self, capacity: int = MAX_INT32) -> None: ...
+    def __init__(self, cmp: Callable[[Any], int] = None) -> None: ...
 
     def __getitem__(self, item): ...
 

docs/_static/custom.css

@@ -0,0 +1,6 @@
+@import url("https://fonts.googleapis.com/css?family=Inconsolata");
+
+body, pre, tt, code {
+    font-family: "Inconsolata", monospace, monospace;
+    font-variant-ligatures: discretionary-ligatures;
+}

docs/api.rst

@@ -7,7 +7,6 @@ API
 
 Functions
 ---------
-------------
 
 .. autofunction:: strhash
 
@@ -20,7 +19,6 @@ Functions
 
 Classes
 -------
-------------
 
 .. autoclass:: CacheMap
     :members:

docs/conf.py

@@ -10,6 +10,7 @@
 # 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 datetime
 import os
 import sys
 
@@ -30,8 +31,9 @@ def get_version():
 
 
 # -- Project information -----------------------------------------------------
-project = "ctools"
-copyright = "2019, ko-han"
+build_at = datetime.date.today().strftime("%a %b %d %Y")
+project = "CTools"
+copyright = "2019, ko-han.    Last updated on " + build_at
 author = "ko-han"
 
 # The full version, including alpha/beta/rc tags
@@ -61,6 +63,14 @@ def get_version():
 
 pygments_style = "sphinx"
 
+rst_epilog = """\n
+.. |ProjectVersion| replace:: {version}
+.. |ProjectName| replace:: {project}
+.. |BuildAt| replace:: {build_at}
+""".format(
+    project=project, version=version, build_at=build_at,
+)
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -75,12 +85,30 @@ def get_version():
 
 html_title = "%s v%s Manual" % (project, version)
 
-# -- sphinx.ext.autodoc -----------------------------------------------------
+font_family = '"Inconsolata", monospace, monospace'
+description = (
+    "A collection of useful data structures and functions written in C for Python."
+)
+html_theme_options = {
+    "github_user": "ko-han",
+    "github_repo": "python-ctools",
+    "github_banner": "false",
+    "github_button": "true",
+    "description": description,
+    "fixed_sidebar": "true",
+    "show_relbars": "true",
+    "code_font_family": font_family,
+    "font_family": font_family,
+    "head_font_family": font_family,
+}
+
+# -- sphinx.ext.autodoc ------------------------------------------------------
 autodoc_docstring_signature = True
 autodoc_default_flags = ["members"]
 autoclass_content = "class"
+autosummary_generate = True
 
-numpydoc_show_class_members = True
+numpydoc_show_class_members = False
 numpydoc_class_members_toctree = True
 numpydoc_xref_param_type = True
 

docs/index.rst

@@ -1,10 +1,7 @@
-.. ctools documentation master file, created by
-   sphinx-quickstart on Mon Sep 23 00:12:18 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+CTools Documentation
+====================
 
-Welcome to ctools's documentation!
-==================================
+Welcome! This is the documentation for |ProjectName| |ProjectVersion|, last updated |BuildAt|.
 
 
 Install

src/cachemap.c

@@ -744,7 +744,7 @@ static PyObject *CacheMap_tp_richcompare(PyObject *self, PyObject *other,
 }
 
 PyDoc_STRVAR(CacheMap__doc__, "CacheMap(maxsize=None, /)\n\n"
-                              "A fast CacheMap behaving much like dict.\n\n"
+                              "A fast LFU (least frequently used) mapping.\n\n"
                               "Default max size is C ``INT32_MAX``.\n\n"
                               "Examples\n"
                               "--------\n"

src/channel.c

@@ -467,7 +467,7 @@ static PyMethodDef Channel_methods[] = {
 };
 
 PyDoc_STRVAR(Channel_Doc, "Channel(size=None, /)\n\n"
-                          "A channel support send and safe resume.\n"
+                          "A channel support sending and safe consuming.\n"
                           "Default size is C ``MAX_INT32``\n\n"
                           "Examples\n"
                           "--------\n"

src/rbtree.c

@@ -1210,13 +1210,16 @@ static PyObject *RBTree_tp_iter(CtsRBTree *tree) {
 
 PyDoc_STRVAR(RBTree__doc__,
              "SortedMap(cmp=None, /)\n\n"
-             "A sorted map base on red-black tree.\n"
-             "`cmp` is a optional callable receive two keys, and "
-             "return negative integer if `k1 < k2`, "
-             "return positive integer if `k1 > k2`, "
-             "return 0 if `k1 == k2`.\n"
-             "It's every similar to standard C library qsort comparator.\n"
-             "\n.. versionadded:: 0.2.0\n"
+             "A sorted map base on red-black tree.\n\n"
+             ".. versionadded:: 0.2.0\n"
+             "Parameters\n"
+             "----------\n"
+             "cmp : typing.Callable[[typing.Any], int]\n"
+             "  A optional callable receive two keys, that\n"
+             "  return negative integer if `k1 < k2`, \n"
+             "  return positive integer if `k1 > k2`, \n"
+             "  return 0 if `k1 == k2`.\n"
+             "  It's every similar to standard C library qsort comparator.\n"
              "\n"
              "Examples\n"
              "--------\n"

src/ttlcache.c

@@ -629,22 +629,23 @@ static PyObject *TTLCache_tp_richcompare(PyObject *self, PyObject *other,
   }
 }
 
-PyDoc_STRVAR(TTLCache__doc__, "TTLCache(ttl=None)\n\n"
-                              "A fast TTLCache behaving much like dict. All "
-                              "key will expire after `ttl` seconds.\n"
-                              "\n"
-                              "Default ttl is 1 minute.\n\n"
-                              "Examples\n"
-                              "--------\n"
-                              ">>> import ctools\n"
-                              ">>> import time\n"
-                              ">>> cache = ctools.TTLCache(5)\n"
-                              ">>> cache['foo'] = 'bar'\n"
-                              ">>> cache['foo']\n"
-                              "'bar'\n"
-                              ">>> time.sleep(5)\n"
-                              ">>> 'foo' in cache\n"
-                              "False\n");
+PyDoc_STRVAR(
+    TTLCache__doc__,
+    "TTLCache(ttl=None)\n\n"
+    "A mapping that keys expire and unreachable after ``ttl`` seconds.\n"
+    "\n"
+    "Default ``ttl`` is 1 minute.\n\n"
+    "Examples\n"
+    "--------\n"
+    ">>> import ctools\n"
+    ">>> import time\n"
+    ">>> cache = ctools.TTLCache(5)\n"
+    ">>> cache['foo'] = 'bar'\n"
+    ">>> cache['foo']\n"
+    "'bar'\n"
+    ">>> time.sleep(5)\n"
+    ">>> 'foo' in cache\n"
+    "False\n");
 
 static PyTypeObject TTLCache_Type = {
     /* clang-format off */