From 0d758dbf1e746404110dd31ccd9f07a4ff2c40cb Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Thu, 26 Dec 2019 17:20:46 +0000 Subject: [PATCH] added docs --- .gitignore | 1 + docs/Makefile | 20 +++++++++ docs/make.bat | 35 ++++++++++++++++ docs/source/conf.py | 68 +++++++++++++++++++++++++++++++ docs/source/index.rst | 20 +++++++++ docs/source/reference.rst | 8 ++++ docs/source/reference/console.rst | 5 +++ make.bat | 35 ++++++++++++++++ rich/console.py | 12 +++--- 9 files changed, 199 insertions(+), 5 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/reference.rst create mode 100644 docs/source/reference/console.rst create mode 100644 make.bat diff --git a/.gitignore b/.gitignore index 22393bf1..a586b1d6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ .DS_Store .vscode mypy_report +docs/build # Byte-compiled / optimized / DLL files __pycache__/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# 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 = 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 + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..6247f7e2 --- /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/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..9b8c3854 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,68 @@ +# 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 ----------------------------------------------------- + + +import pkg_resources + +import sphinx_rtd_theme + +html_theme = "sphinx_rtd_theme" + +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +project = "Rich" +copyright = "2019, Will McGugan" +author = "Will McGugan" + +# The full version, including alpha/beta/rc tags +release = pkg_resources.get_distribution("rich").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 = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", +] + +# 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 = [] + + +# -- 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"] + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..ffeb8344 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. Rich documentation master file, created by + sphinx-quickstart on Thu Dec 26 17:03:20 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Rich's documentation! +================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + reference.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/reference.rst b/docs/source/reference.rst new file mode 100644 index 00000000..a88fe79d --- /dev/null +++ b/docs/source/reference.rst @@ -0,0 +1,8 @@ +Reference +========= + +.. toctree:: + :maxdepth: 3 + + reference/console.rst + \ No newline at end of file diff --git a/docs/source/reference/console.rst b/docs/source/reference/console.rst new file mode 100644 index 00000000..ed08b972 --- /dev/null +++ b/docs/source/reference/console.rst @@ -0,0 +1,5 @@ +rich.console +============ + +.. automodule:: rich.console + :members: Console diff --git a/make.bat b/make.bat new file mode 100644 index 00000000..6247f7e2 --- /dev/null +++ b/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/rich/console.py b/rich/console.py index bb60f2e1..3fcf80a3 100644 --- a/rich/console.py +++ b/rich/console.py @@ -159,7 +159,7 @@ class Console: color_system: Optional[ Literal["auto", "standard", "256", "truecolor"] ] = "auto", - styles: Dict[str, Style] = DEFAULT_STYLES, + styles: Dict[str, Style] = None, file: IO = None, width: int = None, height: int = None, @@ -170,7 +170,7 @@ class Console: log_time_format: str = "[%X] ", ): - self._styles = ChainMap(styles) + self._styles = ChainMap(DEFAULT_STYLES if styles is None else styles) self.file = file or sys.stdout self._width = width self._height = height @@ -249,7 +249,7 @@ class Console: Returns: bool: True if the console writting to a device capable of - understanding terminal codes, otherwise False. + understanding terminal codes, otherwise False. """ isatty = getattr(self.file, "isatty", None) return False if isatty is None else isatty() @@ -722,7 +722,7 @@ class Console: self, theme: Theme = None, clear: bool = True, - code_format=CONSOLE_HTML_FORMAT, + code_format: str = None, inline_styles: bool = False, ) -> str: """Generate HTML from console contents (requires record=True argument in constructor). @@ -747,6 +747,8 @@ class Console: _theme = theme or themes.DEFAULT stylesheet = "" + render_code_format = CONSOLE_HTML_FORMAT if code_format is None else code_format + if inline_styles: for text, style in Segment.simplify(self._record_buffer): if style: @@ -773,7 +775,7 @@ class Console: stylesheet_append(f".r{style_number} {{{style_rule}}}") stylesheet = "\n".join(stylesheet_rules) - rendered_code = code_format.format( + rendered_code = render_code_format.format( code="".join(fragments), stylesheet=stylesheet, foreground=_theme.foreground_color.hex,