From 29d1f3921e5421fd7cb2e1846350297ce96efb48 Mon Sep 17 00:00:00 2001 From: bastimeyer Date: Wed, 23 Nov 2022 21:28:14 +0100 Subject: [PATCH] docs: fix man page links in HTML docs - Update Makefile and define DOCSDIR variable - Add `man` sphinx build tag to the `man` make-target - Exclude `_man.rst` if the `man` build tag is set - Revert b45e685f --- .github/workflows/main.yml | 4 ++-- docs/Makefile | 43 +++++++++++++++++++------------------- docs/conf.py | 14 ++++++++++++- 3 files changed, 37 insertions(+), 24 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2e597766..0beaf0e6 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -80,7 +80,7 @@ jobs: - name: Install dependencies run: | ./script/install-dependencies.sh - python -m pip install -r docs-requirements.txt sphinx==5.2.3 + python -m pip install -r docs-requirements.txt - name: Build run: make --directory=docs html man @@ -103,7 +103,7 @@ jobs: - name: Install dependencies run: | ./script/install-dependencies.sh - python -m pip install -r docs-requirements.txt sphinx==5.2.3 + python -m pip install -r docs-requirements.txt - name: Build run: make --directory=docs html - name: Deploy diff --git a/docs/Makefile b/docs/Makefile index a7da25fa..2c4ee36f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,14 +5,15 @@ SPHINXOPTS = -W SPHINXBUILD = sphinx-build PAPER = +DOCSDIR = . BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) # the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext @@ -42,38 +43,38 @@ clean: -rm -rf $(BUILDDIR)/* html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" @@ -82,7 +83,7 @@ qthelp: @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/streamlink.qhc" devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" @@ -91,63 +92,63 @@ devhelp: @echo "# devhelp" epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) -t man $(DOCSDIR) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/texinfo @echo @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(DOCSDIR) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/conf.py b/docs/conf.py index 0da15976..30a4bfc2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -216,10 +216,22 @@ htmlhelp_basename = 'streamlinkdoc' # -- Options for manual page output -------------------------------------------- +# Only include the man page in builds with the "man" tag set: via `-t man` (see Makefile) + +# noinspection PyUnresolvedReferences +if not tags.tags.get("man"): # type: ignore[name-defined] + exclude_patterns.append("_man.rst") + # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('_man', 'streamlink', 'extracts streams from various services and pipes them into a video player of choice', ['Streamlink Contributors'], 1) + ( + "_man", + "streamlink", + "extracts streams from various services and pipes them into a video player of choice", + ["Streamlink Contributors"], + 1, + ), ] # If true, show URL addresses after external links.