Generate manpage with sphinx and add it to package (#165)

Author: dadav

.github/workflows/publish.yml

@@ -19,6 +19,26 @@ jobs:
       with:
         python-version: '3.7'
 
+    - name: Install sphinx toolset
+      run: >-
+        python -m
+        pip install
+        sphinx
+        sphinx-argparse
+        --user
+
+    - name: Install tldr dependencies
+      run: >-
+        python -m
+        pip install
+        -r
+        requirements.txt
+        --user
+
+    - name: Generate the manpage
+      working-directory: docs
+      run: make man
+
     - name: Install pep517
       run: >-
         python -m

.github/workflows/test.yml

@@ -18,11 +18,31 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install Dependencies
+    - name: Install developer dependencies
       run: |
         python3 -m pip install -U pip
         python3 -m pip install -U pytest pytest-runner flake8
 
+    - name: Install sphinx dependencies
+      run: >-
+        python -m
+        pip install
+        sphinx
+        sphinx-argparse
+        --user
+
+    - name: Install tldr dependencies
+      run: >-
+        python -m
+        pip install
+        -r
+        requirements.txt
+        --user
+
+    - name: Generate the manpage
+      working-directory: docs
+      run: make man
+
     - name: Lint codebase
       run: python3 -m flake8
 

docs/.gitignore

@@ -0,0 +1 @@
+.doctrees

docs/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = man
+
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found.)
+endif
+
+.PHONY: man Makefile clean
+
+man:
+	$(SPHINXBUILD) -b man $(SOURCEDIR) $(BUILDDIR)/
+
+clean:
+	rm -rf $(BUILDDIR)/*

docs/conf.py

@@ -0,0 +1,32 @@
+# 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.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# -- Project information -----------------------------------------------------
+
+project = 'tldr'
+copyright = '2014, Felix Yan'
+author = 'Felix Yan'
+from tldr import __version__  # noqa: E402
+release = __version__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinxarg.ext'
+]

docs/index.rst

@@ -0,0 +1,12 @@
+.. tldr documentation master file, created by
+   sphinx-quickstart on Mon Oct  4 20:14:33 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to tldr's documentation!
+================================
+
+.. argparse::
+   :filename: ../tldr.py
+   :func: create_parser
+   :prog: tldr

requirements.txt

@@ -0,0 +1,3 @@
+termcolor
+colorama
+argcomplete

setup.py

@@ -11,6 +11,9 @@
     raise SystemExit("Could not determine version to use")
 version = version.group(1)
 
+with open('requirements.txt') as f:
+    required = f.read().splitlines()
+
 setup(
     name='tldr',
     author='Felix Yan',
@@ -26,7 +29,8 @@
             "tldr = tldr:cli"
         ]
     },
-    install_requires=['termcolor', 'colorama', 'argcomplete'],
+    data_files=[('share/man/man1', ['docs/man/tldr.1'])],
+    install_requires=required,
     tests_require=[
         'pytest',
         'pytest-runner',

tldr.py

@@ -376,7 +376,7 @@ def update_cache(language=None):
         sys.exit("Error: Unable to update cache from " + DOWNLOAD_CACHE_LOCATION)
 
 
-def main():
+def create_parser():
     parser = ArgumentParser(
         prog="tldr",
         usage="tldr command [options]",
@@ -437,6 +437,12 @@ def main():
         'command', type=str, nargs='*', help="command to lookup", metavar='command'
     ).completer = argcomplete.completers.ChoicesCompleter(get_commands())
 
+    return parser
+
+
+def main():
+    parser = create_parser()
+
     argcomplete.autocomplete(parser)
     options = parser.parse_args()