From ab6ee1060ed60f5c10b27c79b8af417d773ac288 Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Fri, 17 Sep 2021 11:20:34 -0400 Subject: [PATCH 01/10] Initial sphinx setup --- docs/Makefile | 21 +++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ docs/source/api.rst | 8 ++++++++ docs/source/changelog.rst | 4 ++++ docs/source/conf.py | 37 +++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 17 +++++++++++++++++ 6 files changed, 122 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/api.rst create mode 100644 docs/source/changelog.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..aacb7b7 --- /dev/null +++ b/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 ?= -a -E +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + rm -rf "$(BUILDDIR)" + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..7c98b4a --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,8 @@ +API Reference +============= + + +.. autoclass:: ansi2html.Ansi2HTMLConverter + :members: + :undoc-members: + :inherited-members: diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 0000000..b2f5387 --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1,4 @@ +Changelog +========= + +.. include:: ../../changelog.rst diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..78665ab --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,37 @@ +# 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 + +from pathlib import Path +from setuptools_scm import get_version + +# -- Project information ----------------------------------------------------- + +project = 'ansi2html' +copyright = '2021, Ralph Bean, Robin Schneider and various contributors' +author = 'Ralph Bean, Robin Schneider and various contributors' + +# The full version, including alpha/beta/rc tags +release = get_version(root='../..', relative_to=__file__) + +# -- 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 = ['sphinx.ext.autodoc', 'sphinx_rtd_theme'] + +# 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 = [] + + +# -- 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 = 'sphinx_rtd_theme' diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..a511c05 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,17 @@ + +.. include:: ../../README.rst + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + index + api + changelog + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` From 993cb0d36c11dc734453a66648ec7181508c49d3 Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:17:23 -0400 Subject: [PATCH 02/10] Simpler sphinx args --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index aacb7b7..6b154f8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= -a -E +SPHINXOPTS ?= -aE SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build From 4a91662d7b7a0b39e480b70a318643f77f743cc1 Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:33:25 -0400 Subject: [PATCH 03/10] Add tox env --- tox.ini | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/tox.ini b/tox.ini index e0c0d72..56db426 100644 --- a/tox.ini +++ b/tox.ini @@ -54,3 +54,12 @@ commands = whitelist_externals = rm sh + +[testenv:docs] +description = Generate Sphinx docs under build/docs +deps = + Sphinx + setuptools_scm + sphinx_rtd_theme +commands = + sphinx-build -aE -b html {toxinidir}/docs/source {toxinidir}/build/docs From 5cd97ff02aaee67fb218686f89497b038b946466 Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:33:54 -0400 Subject: [PATCH 04/10] Fix docs and add docs for the convert method. --- ansi2html/converter.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ansi2html/converter.py b/ansi2html/converter.py index 2465d56..a9e9427 100644 --- a/ansi2html/converter.py +++ b/ansi2html/converter.py @@ -246,6 +246,7 @@ class Ansi2HTMLConverter: """Convert Ansi color codes to CSS+HTML Example: + >>> conv = Ansi2HTMLConverter() >>> ansi = " ".join(sys.stdin.readlines()) >>> html = conv.convert(ansi) @@ -544,6 +545,11 @@ def attrs(self): return self._attrs def convert(self, ansi, full=True, ensure_trailing_newline=False): + r""" + :param ansi: ANSI sequence to convert. + :param full: Whether to include the full HTML document or only the body. + :param ensure_trailing_newline: Ensures that ``\n`` character is present at the end of the output. + """ attrs = self.prepare(ansi, ensure_trailing_newline=ensure_trailing_newline) if not full: return attrs["body"] From f24211274f5f1005750f78c2035a526d0daac5a8 Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:34:08 -0400 Subject: [PATCH 05/10] Add doctest support --- docs/source/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 78665ab..74c2782 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -4,7 +4,6 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -from pathlib import Path from setuptools_scm import get_version # -- Project information ----------------------------------------------------- @@ -21,14 +20,15 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme'] +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx_rtd_theme'] # 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 = [] - # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for From 4d544cc88017dc6c32d9478401d764f791f3c428 Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:34:23 -0400 Subject: [PATCH 06/10] Fix sidebar --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index a511c05..f87de4c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,7 +5,7 @@ :maxdepth: 1 :caption: Contents: - index + self api changelog From 826c80b532ce4d12af2d5989682b9a3d00d3214f Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:39:44 -0400 Subject: [PATCH 07/10] Use extras_require instead of listing packages in tox.ini. --- setup.cfg | 6 ++++++ tox.ini | 5 +---- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/setup.cfg b/setup.cfg index b9b0016..dbfd5d9 100644 --- a/setup.cfg +++ b/setup.cfg @@ -46,6 +46,12 @@ console_scripts = [options.packages.find] where = . +[options.extras_require] +docs = + Sphinx + setuptools_scm + sphinx_rtd_theme + [flake8] format = pylint # E203: https://github.com/python/black/issues/315 diff --git a/tox.ini b/tox.ini index 56db426..80295cb 100644 --- a/tox.ini +++ b/tox.ini @@ -57,9 +57,6 @@ whitelist_externals = [testenv:docs] description = Generate Sphinx docs under build/docs -deps = - Sphinx - setuptools_scm - sphinx_rtd_theme +extras = docs commands = sphinx-build -aE -b html {toxinidir}/docs/source {toxinidir}/build/docs From 5cce66390bb1037535ea2b7075fd831197d97888 Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:40:02 -0400 Subject: [PATCH 08/10] Add readthedocs file. --- readthedocs.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 readthedocs.yml diff --git a/readthedocs.yml b/readthedocs.yml new file mode 100644 index 0000000..7851e8e --- /dev/null +++ b/readthedocs.yml @@ -0,0 +1,13 @@ +version: 2 + +sphinx: + fail_on_warning: false + +python: + version: 3.8 + system_packages: false + install: + - method: pip + path: . + extra_requirements: + - docs From cf28fafb85aa2bd39d8855b1bd6a67a17bc15a5a Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:46:19 -0400 Subject: [PATCH 09/10] Add read the docs link in the readme. --- README.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.rst b/README.rst index e564fbc..7ec9b7f 100644 --- a/README.rst +++ b/README.rst @@ -13,6 +13,8 @@ Convert text with ANSI color codes to HTML or to LaTeX. Inspired by and developed off of the work of `pixelbeat`_ and `blackjack`_. +`Read the docs `_ for more informations. + Build Status ------------ From 2370c0c626ca437cabd50d8c51a19bbeee348de9 Mon Sep 17 00:00:00 2001 From: tristanlatr Date: Sat, 18 Sep 2021 19:57:03 -0400 Subject: [PATCH 10/10] Lint stuff. --- README.rst | 2 +- ansi2html/converter.py | 4 ++-- docs/source/conf.py | 14 ++++++-------- docs/source/index.rst | 2 +- 4 files changed, 10 insertions(+), 12 deletions(-) diff --git a/README.rst b/README.rst index 7ec9b7f..a0a2a5f 100644 --- a/README.rst +++ b/README.rst @@ -13,7 +13,7 @@ Convert text with ANSI color codes to HTML or to LaTeX. Inspired by and developed off of the work of `pixelbeat`_ and `blackjack`_. -`Read the docs `_ for more informations. +`Read the docs `_ for more informations. Build Status ------------ diff --git a/ansi2html/converter.py b/ansi2html/converter.py index a9e9427..88da7ec 100644 --- a/ansi2html/converter.py +++ b/ansi2html/converter.py @@ -546,8 +546,8 @@ def attrs(self): def convert(self, ansi, full=True, ensure_trailing_newline=False): r""" - :param ansi: ANSI sequence to convert. - :param full: Whether to include the full HTML document or only the body. + :param ansi: ANSI sequence to convert. + :param full: Whether to include the full HTML document or only the body. :param ensure_trailing_newline: Ensures that ``\n`` character is present at the end of the output. """ attrs = self.prepare(ansi, ensure_trailing_newline=ensure_trailing_newline) diff --git a/docs/source/conf.py b/docs/source/conf.py index 74c2782..ce0e1d9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -8,21 +8,19 @@ # -- Project information ----------------------------------------------------- -project = 'ansi2html' -copyright = '2021, Ralph Bean, Robin Schneider and various contributors' -author = 'Ralph Bean, Robin Schneider and various contributors' +project = "ansi2html" +copyright = "2021, Ralph Bean, Robin Schneider and various contributors" +author = "Ralph Bean, Robin Schneider and various contributors" # The full version, including alpha/beta/rc tags -release = get_version(root='../..', relative_to=__file__) +release = get_version(root="../..", relative_to=__file__) # -- 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 = ['sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx_rtd_theme'] +extensions = ["sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx_rtd_theme"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -34,4 +32,4 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +html_theme = "sphinx_rtd_theme" diff --git a/docs/source/index.rst b/docs/source/index.rst index f87de4c..054f37f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,7 @@ .. toctree:: :maxdepth: 1 :caption: Contents: - + self api changelog