Add man page to package

7 files changed, 290 insertions, 12 deletions

diff --git a/MANIFEST.in b/MANIFEST.in
index 1de226b..7533e12 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -5,3 +5,4 @@ exclude .gitignore
 exclude Dockerfile
 exclude make_release.py
 prune old
+include p2r.1
diff --git a/Makefile b/Makefile
index bcbc420..6a4a460 100644
--- a/Makefile
+++ b/Makefile
@@ -7,7 +7,7 @@ PACKAGE=paper2remarkable
 DOC_DIR='./docs/'
 VENV_DIR=/tmp/p2r_venv/
 
-.PHONY: help dist venv
+.PHONY: help dist venv docs
 
 .DEFAULT_GOAL := help
 
@@ -35,22 +35,15 @@ clean: ## Clean build dist and egg directories left after install
 	rm -rf ./$(PACKAGE).egg-info
 	rm -rf $(VENV_DIR)
 	rm -f MANIFEST
+	rm -f ./p2r.1
 	find . -type f -iname '*.pyc' -delete
 	find . -type d -name '__pycache__' -empty -delete
 
-dist: ## Make Python source distribution
+dist: docs ## Make Python source distribution
 	python setup.py sdist bdist_wheel
 
-docs: doc
-doc: install ## Build documentation with Sphinx
-	source $(VENV_DIR)/bin/activate && m2r README.md && mv README.rst $(DOC_DIR)
-	source $(VENV_DIR)/bin/activate && m2r CHANGELOG.md && mv CHANGELOG.rst $(DOC_DIR)
-	cd $(DOC_DIR) && \
-		rm source/* && \
-		source $(VENV_DIR)/bin/activate && \
-		sphinx-apidoc -H 'Paper2Remarkable API Documentation' -o source ../$(PACKAGE) && \
-		touch source/AUTOGENERATED
-	$(MAKE) -C $(DOC_DIR) html
+docs:
+	$(MAKE) -C $(DOC_DIR) clean && $(MAKE) -C $(DOC_DIR) man
 
 venv: $(VENV_DIR)/bin/activate
 
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..4c617df
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,71 @@
+# Makefile for paper2remarkable documentation
+#
+# Author: G.J.J. van den Burg
+# Copyright (c) 2020 G.J.J. van den Burg
+# License: See LICENSE file
+#
+
+SHELL := bash
+.SHELLFLAGS := -eu -o pipefail -c
+MAKEFLAGS += --no-builtin-rules
+
+VENV_DIR=/tmp/p2r_docs/
+OUTPUT_DIR=./output
+
+PACKAGE       = p2r
+SPHINXBUILD   = sphinx-build
+ALLSPHINXOPTS = -d .build/doctrees .
+
+.PHONY: all
+
+all: man
+
+############
+# Man page #
+############
+
+.PHONY: man output-dir clean_output
+
+man: $(OUTPUT_DIR)/$(PACKAGE).1
+	cp $< ../$(PACKAGE).1
+	@echo "Generated man page copied to ../$(PACKAGE).1"
+
+$(OUTPUT_DIR)/$(PACKAGE).1: man.rst | output-dir
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(OUTPUT_DIR)
+
+man.rst: man.md venv
+	source $(VENV_DIR)/bin/activate && m2r man.md
+
+output-dir:
+	mkdir -p $(OUTPUT_DIR)
+	mkdir -p _static
+
+clean_output:
+	rm -f man.rst
+	rm -rf $(OUTPUT_DIR)
+	rm -rf _static
+
+#######################
+# Virtual environment #
+#######################
+
+.PHONY: venv clean_venv
+
+venv: $(VENV_DIR)/bin/activate
+
+$(VENV_DIR)/bin/activate:
+	test -d $(VENV_DIR) || python -m venv $(VENV_DIR)
+	source $(VENV_DIR)/bin/activate && pip install m2r
+	touch $(VENV_DIR)/bin/activate
+
+clean_venv:
+	rm -rf $(VENV_DIR)
+
+############
+# Clean up #
+############
+
+.PHONY: venv
+
+clean: clean_venv clean_output
+	rm -f ../$(PACKAGE).1
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..92961c1
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,62 @@
+# 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 = "paper2remarkable"
+copyright = "2020, G.J.J. van den Burg"
+author = "Gertjan van den Burg"
+
+
+# -- 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 = []
+
+# 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"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# 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 = ["_static"]
+
+# Man page
+man_pages = [
+    (
+        "man",
+        "p2r",
+        "Fetch an academic paper or web article and send it to the reMarkable tablet",
+        author + " & other helpful contributors.",
+        1,
+    )
+]
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/index.rst
diff --git a/docs/man.md b/docs/man.md
new file mode 100644
index 0000000..dcaf594
--- /dev/null
+++ b/docs/man.md
@@ -0,0 +1,150 @@
+# paper2remarkable
+
+## SYNOPSIS
+
+```
+p2r [OPTION]... [INPUT]...
+```
+
+## DESCRIPTION
+
+Fetch an academic paper, local pdf file, or any web article and send it to the 
+reMarkable tablet. The input to the script can be a URL to a PDF file or 
+article on a website, or a local file. For supported scientific outlets, the 
+program will collect the metadata for the paper and create a nice filename 
+(unless ``--filename`` is specified). See [SUPPORTED 
+SOURCES](#supported-sources) for an overview of supported scientific outlets.
+
+By default, paper2remarkable crops the unnecessary whitespace from a PDF file 
+to make the paper fit better on the reMarkable. The default setting yields a 
+left-aligned document on the reMarkable which can be useful for taking margin 
+notes. Alternatively, the program supports the ``--center``, ``--right``, and 
+``--no-crop`` options to change this crop setting.
+
+## OPTIONS
+
+Basic options:
+
+-b, --blank
+      Add a blank page after every page of the PDF document. This can be 
+      useful for taking notes on papers.
+
+-e, --experimental
+      Enable the experimental features of paper2remarkable. See below under 
+      [EXPERIMENTAL FEATURES](#experimental-features) for an overview.
+
+-f, --filename=FILENAME
+      Filename to use for the file on reMarkable. If you specify multiple 
+      ``INPUT`` files and want to use a specific filename for each, you can 
+      specify ``--filename`` for each ``INPUT`` source by repeating it.
+
+-h, --help
+      Show help message and exit.
+
+-v, --verbose
+      Enable verbose mode of paper2remarkable. By default the program prints 
+      no output.
+
+-V, --version
+      Show the version and exit.
+
+Crop options:
+
+-c, --center
+      Center the PDF on the page.
+
+-k, --no-crop
+      Don't crop the document at all.
+
+-r, --right
+      Right-align the document on the reMarkable so the menu doesn't cover it.
+
+reMarkable options:
+
+-n, --no-upload
+      Don't upload the document to the reMarkable, save the output in the 
+      current working dir.
+
+-p, --remarkable-path=DIR
+      The directory on the reMarkable where the document will be uploaded to. 
+      If the target directory does not exist it will be created. If not 
+      specified, the root directory will be used.
+
+System settings:
+
+You'll only need to specify these options if the programs are not available on 
+the PATH variable.
+
+--gs=GS
+      Path to the GhostScript executable.
+
+--pdftoppm=PDFTOPPM
+      Path to pdftoppm executable (default: pdftoppm)
+
+--pdftk=PDFTK
+      Path to PDFtk executable (default: pdftk)
+
+--qpdf=QPDF
+      Path to qpdf executable (default: qpdf)
+
+--rmapi=RMAPI
+      Path to rmapi executable (default: rmapi)
+
+Developer options:
+
+-d, --debug
+      Debug mode, when used the program doesn't upload the document to the 
+      reMarkable by default and leaves the temporary directory with 
+      intermediate files.
+
+## SUPPORTED SOURCES
+
+The following scientific sources are currently supported and paper2remarkable 
+will create a filename based on the authors, title, and publication year of 
+the work. For the sources below the program is generally flexible with regards 
+to whether a URL to the PDF or to the abstract page is provided.
+
+- arXiv
+- ACM Digital Library
+- CiteSeerX
+- CVF
+- JMLR
+- Nature
+- NBER
+- NeurIPS
+- OpenReview
+- PMLR
+- PubMed Central
+- SagePub
+- SemanticScholar
+- SpringerLink
+- Taylor & Francis
+
+paper2remarkable also supports a generic URL to a PDF file or a local file, in 
+which case no "nice" filename will be generated.
+
+- A generic URL to a PDF file. This can be considered a fallback option for 
+  when a PDF source is not supported (yet).
+- A local PDF file
+
+Finally, paper2remarkable supports extracting articles from websites. In this 
+case an effort is done to detect the main content of the article and clean up 
+the HTML before sending the file to the reMarkable.
+
+## EXPERIMENTAL FEATURES
+
+Occassionally, experimental (beta) features will be included in 
+paper2remarkable and they will be listed here. You can enable the experimental 
+features using the ``-e`` flag to paper2remarkable.
+
+- The HTML provider currently has an experimental feature to handle lazy 
+  loading of images. Certain websites use a small placeholder image and 
+  subsequently load the main image, which is often stored in a ``data-src`` 
+  attribute in the ``img`` tag. The experimental feature uses the ``data-src`` 
+  attribute as the image source instead of the ``src``.
+
+## BUGS
+
+Please report bugs to:
+
+https://www.github.com/GjjvdBurg/paper2remarkable
diff --git a/setup.py b/setup.py
index 54a8cb1..e79448c 100644
--- a/setup.py
+++ b/setup.py
@@ -86,6 +86,7 @@ setup(
     install_requires=REQUIRED,
     extras_require=EXTRAS,
     include_package_data=True,
+    data_files=[("man/man1", ["p2r.1"])],
     license=LICENSE,
     ext_modules=[],
     entry_points={"console_scripts": ["p2r = paper2remarkable.__main__:main"]},