From c84fdfc1bf68f691518770c465577cd365757de5 Mon Sep 17 00:00:00 2001 From: Gertjan van den Burg Date: Wed, 21 Aug 2024 21:12:55 +0100 Subject: [PATCH] Remove the m2r2 dependency We'll just write the man page in .rst going forward Fixes #145 --- docs/Makefile | 14 +++---- docs/{man.md => man.rst} | 88 +++++++++++++++++++++++----------------- 2 files changed, 56 insertions(+), 46 deletions(-) rename docs/{man.md => man.rst} (81%) diff --git a/docs/Makefile b/docs/Makefile index 6ca9c77..8c193c4 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -15,6 +15,7 @@ OUTPUT_DIR=./output PACKAGE = p2r SPHINXBUILD = sphinx-build ALLSPHINXOPTS = -d .build/doctrees . +PYTHON ?= python .PHONY: all @@ -30,18 +31,15 @@ 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 && m2r2 man.md +$(OUTPUT_DIR)/$(PACKAGE).1: man.rst | output-dir venv + source $(VENV_DIR)/bin/activate && \ + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(OUTPUT_DIR) output-dir: mkdir -p $(OUTPUT_DIR) mkdir -p _static clean_output: - rm -f man.rst rm -rf $(OUTPUT_DIR) rm -rf _static rm -rf .build @@ -55,8 +53,8 @@ clean_output: 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 m2r2 + test -d $(VENV_DIR) || $(PYTHON) -m venv $(VENV_DIR) + source $(VENV_DIR)/bin/activate && pip install sphinx touch $(VENV_DIR)/bin/activate clean_venv: diff --git a/docs/man.md b/docs/man.rst similarity index 81% rename from docs/man.md rename to docs/man.rst index 1952cd5..91bbca6 100644 --- a/docs/man.md +++ b/docs/man.rst @@ -1,28 +1,33 @@ -# paper2remarkable -## SYNOPSIS +paper2remarkable +================ -``` -p2r [OPTION]... [INPUT]... -``` +SYNOPSIS +-------- -## DESCRIPTION +.. code-block:: + + 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 paper +(unless ``--filename`` is specified). See `SUPPORTED +SOURCES <#supported-sources>`_ for an overview of supported scientific paper sources. 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 +notes. Alternatively, the program supports the ``--center``\ , ``--right``\ , and ``--no-crop`` options to change this crop setting. -## OPTIONS +OPTIONS +------- Basic options: @@ -32,12 +37,12 @@ Basic options: -C, --config=FILENAME Read options from a configuration file. A YAML file is supported, see - [CONFIGURATION FILE](#configuration) for further details. By default the + `CONFIGURATION FILE <#configuration>`_ for further details. By default the file at ``~/.paper2remarkable.yml`` is used if it exists. -e, --experimental Enable the experimental features of paper2remarkable. See below under - [EXPERIMENTAL FEATURES](#experimental-features) for an overview. + `EXPERIMENTAL FEATURES <#experimental-features>`_ for an overview. -f, --filename=FILENAME Filename to use for the file on reMarkable. If you specify multiple @@ -117,51 +122,55 @@ Developer options: reMarkable by default and leaves the temporary directory with intermediate files. -## SUPPORTED SOURCES +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 -- ACL Web -- ACM Digital Library -- CVF -- ECCC -- IACR -- JMLR -- Nature -- NBER -- NeurIPS -- OpenReview -- PMLR -- PubMed Central -- SemanticScholar -- SpringerLink + +* arXiv +* ACL Web +* ACM Digital Library +* CVF +* ECCC +* IACR +* JMLR +* Nature +* NBER +* NeurIPS +* OpenReview +* PMLR +* PubMed Central +* SemanticScholar +* SpringerLink 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 + +* 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. +* 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. -## CONFIGURATION FILE +CONFIGURATION FILE +------------------ To avoid having to provide frequently-used command line flags, a configuration file can be created for paper2remarkable. By default it is a YAML file located -at ``~/.paper2remarkable.yml``, but an alternative location can be provided +at ``~/.paper2remarkable.yml``\ , but an alternative location can be provided with the ``--config`` option to the script. -The configuration file consists of three sections: ``core``, ``system``, and +The configuration file consists of three sections: ``core``\ , ``system``\ , and ``html``. In the ``core`` section options for cropping, verbosity, and blank pages can be added, among others. The ``system`` section allows setting paths -to executables such as ``rmapi``, ``pdftk``, etc. Finally, the ``html`` +to executables such as ``rmapi``\ , ``pdftk``\ , etc. Finally, the ``html`` section allows you to provide custom CSS and font urls for formatting the output of web articles. @@ -171,23 +180,26 @@ file. So, for instance, if the configuration file has the setting ``crop: the PDF will be centered. An example file is provided in the repository on -[GitHub](https://www.github.com/GjjvdBurg/paper2remarkable), which also +`GitHub `_\ , which also contains more information on the available options and their values. -## EXPERIMENTAL FEATURES +EXPERIMENTAL FEATURES +--------------------- Occassionally, experimental (beta) features will be included in paper2remarkable and they will be listed here. You can enable the experimental features by using the ``-e`` flag to paper2remarkable. -- The HTML provider currently has an experimental feature to handle lazy + +* The HTML provider currently has an experimental feature to handle lazy loading of images. Certain websites use a small placeholder image and load the main image using Javascript, with the actual image source stored in a ``data-src`` attribute in the ``img`` tag. The experimental feature uses the ``data-src`` attribute as the image source instead of that in the ``src`` attribute. -## BUGS +BUGS +---- Please report bugs to: