jarn.viewdoc 2.7
Python documentation viewer
License: BSD-2-Clause
Requires Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,>=2.7
Keywords: view,rest,rst,package,docs,documentation,rst2html,long-description

============
jarn.viewdoc
============
------------------------------------
Python documentation viewer
------------------------------------

**viewdoc** is a Python package documentation viewer. It converts
reST-formatted text to HTML and displays it in a browser window.
The viewer is typically used to check a package's long description before
uploading it to PyPI.

Contents
========

* Installation_
* Usage_
* Options_
* Arguments_
* Configuration_
* Related_
* Changelog_

Installation
============

viewdoc works with Python 2.7 - 3.11 and all released versions of setuptools.

Use ``pip install jarn.viewdoc`` to install the ``viewdoc`` script.

Usage
=====

``viewdoc [options] [rst-file|egg-dir]``

Options
=======

``-s style, --style=style, or --style``
    Select the custom style added to the HTML output.

``-b browser, --browser=browser``
    Select the browser used for display. For a list of names see the
    `webbrowser`_ module.

``-c config-file, --config-file=config-file``
    Use config-file instead of the default ``~/.viewdoc``.

``-l, --list-styles``
    List available styles and exit.

``-h, --help``
    Print the help message and exit.

``-v, --version``
    Print the version string and exit.

``--no-color``
    Disable output colors.

``--no-browser``
    Print HTML to stdout.

Arguments
=========

``rst-file``
    The reST file to view.

``egg-dir``
    The Python package whose long description to view.
    Defaults to the current working directory.

.. _`webbrowser`: https://docs.python.org/3/library/webbrowser.html#webbrowser.register

Configuration
=============

viewdoc reads style information from its configuration file
``~/.viewdoc``. Edit this file to add your own styles.

Built-in Styles
---------------

``plain``
    Browser default with margins.

``pypi``
    New PyPI style with Google Fonts.

``sans``
    PyPI-like style without Google Fonts (the default).


Related
=======

Also see our Python package releaser `jarn.mkrelease`_.

.. _`jarn.mkrelease`: https://github.com/Jarn/jarn.mkrelease


Changelog
=========

2.7 - 2023-09-23
----------------

- Update tox.ini for latest tox.
  [stefan]

- Filter deprecated config warning.
  [stefan]

- Fix invalid escape sequences.
  [stefan]

- Fix tests for docutils >= 0.20.0.
  [stefan]

2.6 - 2023-01-21
----------------

- Support setuptools >= 65.6.0.
  [stefan]

2.5 - 2022-11-13
----------------

- Support Python 2.7 - 3.11.
  [stefan]

- Do not require setup.py or setup.cfg if pyproject.toml exists.
  [stefan]

- Filter some deprecation warnings.
  [stefan]

- Warn if long_description metadata is missing.
  [stefan]

2.4 - 2022-02-26
----------------

- Support Python 2.7 - 3.10.
  [stefan]

- Fix code block background color in ``pypi`` style.
  [stefan]

- Keep links underlined in ``pypi`` style.
  [stefan]

- Add output colors.
  [stefan]

- Do not require setup.py if setup.cfg exists.
  [stefan]

- Move metadata to setup.cfg.
  [stefan]

- Move tests out of ``jarn.viewdoc`` namespace.
  [stefan]

- Include tests in sdist but not in wheel.
  [stefan]

2.3 - 2019-01-28
----------------

- Support ``python -m jarn.viewdoc``.
  [stefan]

2.2 - 2019-01-25
----------------

- Drop Python 2.6 support, add Python 3.7.
  [stefan]

- Update styles in light of new PyPI (warehouse).
  [stefan]

- Default to ``sans`` style because new PyPI uses Google Fonts.
  [stefan]

- Convert dashes to underscores in config parser optionxform.
  [stefan]

2.1 - 2017-10-06
----------------

- Add MANIFEST.in.
  [stefan]

2.0 - 2017-07-20
----------------

- Update ``pypi`` stylesheet (grey code blocks).
  [stefan]

- Automatically upgrade stylesheet information.
  [stefan]

- Add -b option to specify the browser to use.
  [stefan]

- Protect against bad or incomplete locale settings.
  [stefan]

1.8 - 2017-01-30
----------------

- Support Python 2.6 - 3.6 without 2to3.
  [stefan]

1.7 - 2014-03-22
----------------

- Update PyPI stylesheet links in the face of new python.org.
  [stefan]

- Add new ``pypi`` style and rename previous one to ``classic``.
  [stefan]

1.6 - 2013-11-21
----------------

- Support Python 3.x.
  [stefan]

1.5 - 2012-07-11
----------------

- Restore Python 2.5 compatibility.
  [stefan]

1.4 - 2011-11-25
----------------

- Warn if ``~/.viewdoc`` has errors instead of raising an exception.
  [stefan]

1.3 - 2011-10-31
----------------

- Be more careful with what we put on the PYTHONPATH.
  [stefan]

- Add ``small`` style to the default config.
  [stefan]

1.2 - 2011-07-19
----------------

- Pass the PYTHONPATH to subprocesses.
  [stefan]

- Avoid temp file when extracting the long description.
  [stefan]

- Add -l option to list available styles.
  [stefan]

- Add --*style* shortcut for -s *style*.
  [stefan]

1.1 - 2011-02-08
----------------

- Add -s option to select styles on the command line.
  [stefan]

- In ``pypi`` style, only underline reference links.
  [stefan]

1.0 - 2010-12-30
----------------

- Initial release
  [stefan]