From f9977b727d8a0103b02b316de615c3228cf3f6d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89loi=20Rivard?= Date: Sun, 29 Dec 2019 19:12:42 +0100 Subject: [PATCH] Documentation draft --- README.rst | 2 +- doc/__init__.py | 0 doc/source/__init__.py | 0 doc/source/api.rst | 30 +++++++ doc/source/conf.py | 164 +++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 13 +++ readability/readability.py | 2 +- tox.ini | 13 ++- 8 files changed, 220 insertions(+), 4 deletions(-) create mode 100644 doc/__init__.py create mode 100644 doc/source/__init__.py create mode 100644 doc/source/api.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst diff --git a/README.rst b/README.rst index e85c786..a060f61 100644 --- a/README.rst +++ b/README.rst @@ -50,7 +50,7 @@ Change Log - 0.3 Added Document.encoding, positive\_keywords and negative\_keywords Licensing -========= +-------- This code is under `the Apache License 2.0 `__ license. diff --git a/doc/__init__.py b/doc/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/__init__.py b/doc/source/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000..b0e3bbb --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,30 @@ +Reference +========= + +.. automodule:: readability + :members: + :show-inheritance: + +.. automodule:: readability.browser + :members: + :show-inheritance: + +.. automodule:: readability.cleaners + :members: + :show-inheritance: + +.. automodule:: readability.debug + :members: + :show-inheritance: + +.. automodule:: readability.encoding + :members: + :show-inheritance: + +.. automodule:: readability.htmls + :members: + :show-inheritance: + +.. automodule:: readability.readability + :members: + :show-inheritance: diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..bb26134 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,164 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# readability documentation build configuration file, created by +# sphinx-quickstart on Thu Mar 23 16:29:38 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# 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("../..")) + +import readability + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.ext.intersphinx", + "sphinx.ext.todo", + "recommonmark", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = [".rst", ".md"] + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "readability" +copyright = "2020, Yuri Baburov" +author = "Yuri Baburov" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +# The short X.Y version. +version = readability.__version__ + +# The full version, including alpha/beta/rc tags. +release = readability.__version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = "readabilitydoc" + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [(master_doc, "readability.tex", "Readability Documentation", "Yuri Baburov", "manual")] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "readability", "readability Documentation", [author], 1)] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "readability", + "Readability Documentation", + author, + "readability", + "One line description of project.", + "Miscellaneous", + ) +] + + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..e3bce61 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,13 @@ +.. include:: ../../README.rst + +.. toctree:: + :maxdepth: 2 + + api + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/readability/readability.py b/readability/readability.py index d7caa5b..f559597 100755 --- a/readability/readability.py +++ b/readability/readability.py @@ -178,7 +178,7 @@ class Document: Given a HTML file, extracts the text of the article. :param html_partial: return only the div of the document, don't wrap - in html and body tags. + in html and body tags. Warning: It mutates internal DOM representation of the HTML document, so it is better to call other API methods before this one. diff --git a/tox.ini b/tox.ini index d3c2a7f..2019f35 100644 --- a/tox.ini +++ b/tox.ini @@ -4,10 +4,15 @@ # and then run "tox" from this directory. [tox] -envlist = py27, py35, py36, py37 +envlist = py27, py35, py36, py37, doc [testenv] -deps=pytest +deps = + pytest + doc: sphinx + doc: sphinx_rtd_theme + doc: recommonmark + # This creates the virtual envs with --site-packages so already packages # that are already installed will be reused. This is especially useful on # Windows. Since we use lxml instead of compiling it locally (which in turn @@ -18,3 +23,7 @@ sitepackages=True commands = pip install -r requirements.txt -e ".[test]" py.test + +[testenv:doc] +commands = + python setup.py build_sphinx