Document the Python bindings using Sphinx

Additionally, setup the documentation for
deployment to Read The Docs.

.gitignore

@@ -40,11 +40,14 @@ cpuid_tool/x32
 cpuid_tool/x64
 *.vcxproj.user
 build
-docs
+/docs
 .vscode
 raw.txt
 report.txt
 *__pycache__
+python/docs/_build
+python/docs/doctrees
+python/docs/html
 python/dist
 python/src/libcpuid/_libcpuid_cffi.*
 python/src/libcpuid/libcpuid.h

.readthedocs.yml

@@ -0,0 +1,29 @@
+# Read the Docs configuration file
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: latest
+  apt_packages:
+    - autoconf
+    - libtool
+    - automake
+  jobs:
+    pre_install:
+      - libtoolize
+      - autoreconf --install
+      - mkdir ./install
+      - ./configure --prefix=`pwd`/install
+      - make
+      - make install
+      - pip install cffi
+      - python ./python/ffi_build_rtd.py ./libcpuid/libcpuid.h ./install
+
+sphinx:
+  configuration: python/docs/conf.py
+
+python:
+  install:
+    - requirements: python/docs/requirements.txt

Readme.md

@@ -171,6 +171,13 @@ When no options are present, the program behaves as if it was invoked with
   cpuid_tool "--save=raw.txt --outfile=report.txt --report --verbose"
 ```
 
+### Python bindings
+
+The libcpuid library features Python bindings, which can be installed as a library
+using `python -m pip install libcpuid`. Visit the
+[documentation at Read the Docs](https://libcpuid.readthedocs.io/en/latest/index.html#)
+to see how the library is used.
+
 ## Contributing
 
 Refer to the [dedicated page](CONTRIBUTING.md).

python/README.md

@@ -0,0 +1,8 @@
+# libcpuid
+
+libcpuid is a package that provides Python bindings to
+the C library of the same name. Its main feature is
+CPU identification for the x86 and ARM architectures.
+
+Visit the [documentation at Read the Docs](https://libcpuid.readthedocs.io/en/latest/index.html#)
+to see how the library is used.

python/docs/api/clock.rst

@@ -0,0 +1,6 @@
+Clock and frequency computation
+===============================
+
+.. automodule:: libcpuid.clock
+   :members:
+   :undoc-members:

python/docs/api/enums.rst

@@ -0,0 +1,6 @@
+Enumeration classes
+===================
+
+.. automodule:: libcpuid.enums
+   :members:
+   :undoc-members:

python/docs/api/errors.rst

@@ -0,0 +1,5 @@
+Library exceptions
+==================
+
+.. automodule:: libcpuid.errors
+   :members:

python/docs/api/info.rst

@@ -0,0 +1,22 @@
+Basic CPU information
+=====================
+
+.. autoclass:: libcpuid.info.CPUInfo
+   :members:
+   :exclude-members: from_c
+
+.. autoclass:: libcpuid.info.X86Info
+   :members:
+
+.. autoclass:: libcpuid.info.ARMInfo
+   :members:
+
+.. autoclass:: libcpuid.sgx.SGX
+   :members:
+
+.. autoclass:: libcpuid.sgx.EPC
+   :members:
+
+.. autoclass:: libcpuid.info.SystemInfo
+   :members:
+   :exclude-members: from_c

python/docs/api/libcpuid.rst

@@ -0,0 +1,5 @@
+Top-level library functionality
+===============================
+
+.. automodule:: libcpuid
+    :members:

python/docs/api/msr.rst

@@ -0,0 +1,6 @@
+Model-specific registers
+========================
+
+.. automodule:: libcpuid.msr
+   :members:
+   :undoc-members:

python/docs/api/raw.rst

@@ -0,0 +1,10 @@
+Raw CPU data
+============
+
+.. autoclass:: libcpuid.raw.CPURawData
+   :members:
+   :exclude-members: c_cpu_raw_data
+
+.. autoclass:: libcpuid.raw.CPURawDataArray
+   :members:
+   :exclude-members: c_cpu_raw_data_array

python/docs/conf.py

@@ -0,0 +1,35 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+project = "libcpuid"
+copyright = "2024, Pavol Žáčik"
+author = "Pavol Žáčik"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx_rtd_theme",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+language = "en"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+autodoc_member_order = "bysource"

python/docs/index.rst

@@ -0,0 +1,51 @@
+Welcome to libcpuid's documentation!
+====================================
+
+**libcpuid** provides a Python interface
+to the libcpuid C library.
+
+.. code-block:: python
+
+   import sys
+   import libcpuid
+   from libcpuid.errors import LibcpuidError
+   from libcpuid.info import CPUInfo
+   from libcpuid.enums import CPUFeature, CPUVendor
+
+   # print the version of the libcpuid library
+   print(libcpuid.version())
+
+   # print the number of CPU cores
+   print(libcpuid.get_total_cpus())
+
+   # check if the cpuid instruction is available
+   if not libcpuid.cpuid_present():
+      print("CPUInfo instruction is not available")
+      sys.exit(1)
+
+   try:
+      # identify the current CPU and print some
+      # information about it
+      cpu_info = CPUInfo.from_current_cpu()
+      print(cpu_info.vendor)
+      print(cpu_info.architecture)
+      print(CPUFeature.FPU in cpu_info.features)
+
+      # print the list of all Intel CPU code names
+      print(libcpuid.get_cpu_list(CPUVendor.INTEL))
+   except LibcpuidError as err:
+      print(err.message)
+      sys.exit(1)
+
+
+.. toctree::
+   :maxdepth: 2
+
+   Home <self>
+   api/libcpuid
+   api/info
+   api/msr
+   api/enums
+   api/raw
+   api/clock
+   api/errors

python/docs/requirements.txt

@@ -0,0 +1 @@
+sphinx-rtd-theme

python/ffi_build_rtd.py

@@ -0,0 +1,31 @@
+"""
+Script for compiling the C FFI for the live documentation.
+"""
+
+import sys
+import os
+from cffi import FFI
+
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+from _ffi_build_utils import (  # pylint: disable=import-error, wrong-import-position
+    preprocess_header,
+    eval_sizeofs,
+)
+
+if __name__ == "__main__":
+    header_path = sys.argv[1]
+    install_dir = sys.argv[2]
+    library_dir = os.path.join(os.getcwd(), install_dir, "lib")
+    include_dir = os.path.join(install_dir, "include", "libcpuid")
+    ffibuilder = FFI()
+    ffibuilder.cdef(eval_sizeofs(preprocess_header(header_path), [f"-I{include_dir}"]))
+    ffibuilder.set_source(
+        "python.src.libcpuid._libcpuid_cffi",
+        "#include <libcpuid.h>",
+        libraries=["cpuid"],
+        library_dirs=[library_dir],
+        include_dirs=[include_dir],
+        extra_link_args=[f"-Wl,-rpath={library_dir}"],
+    )
+    ffibuilder.compile(verbose=True)