Создание единой HTML-страницы справки для модуля, функции, класса, аналогичного R

Question

Я ищу способ облегчить себе путь в новые модули, широко используя help().

Проблема, с которой я сейчас сталкиваюсь, заключается в том, что вывод очень полезен, но его трудно прокрутить в интерактивном переводчике. То, что я ищу, это способ для меня исследовать модули Python способом, аналогичным тому, как R обрабатывает документацию (при использовании R PRoject).

R выводит один HTML-файл, который позволяет пролистывать параметры, функции; Я использую Python 2.7 на Windows.

Я нашел pydoc, который выводит именно то, что я ищу, на консоль, но я не совсем уверен, как мне перейти от "веб-сервера", документирующего все мои установленные пакеты, к простому обслуживанию и открытию одного HTML-страницу, когда я набираю help(x), выводя то, что она обычно выводит в интерпретаторе.

Любая помощь с благодарностью.

Answer 1

Спасибо за ответы. Мое окончательное решение - это комбинация двух ваших методов:

• Я импортировал TemporaryDirectory(), как упоминалось выше;
• Затем я вызываю pydoc.writedoc(x) для создания html-файла в temp. папки;
• Я использовал другой фрагмент кода для подавления печати "write x.html" из pydoc;
• Я использовал webbrowser.open_new(url), чтобы открыть новую страницу в браузере по умолчанию.

Вызов help(os) теперь генерирует временный HTML-файл (в pydoc) и открывает его в моем стандартном браузере; это было именно то, что мне было нужно.

from __future__ import print_function

import pydoc
import os
import sys
import time
import webbrowser

import warnings as _warnings
import os as _os

from tempfile import mkdtemp
from contextlib import contextmanager


@contextmanager
def suppress_stdout():
    """ Suppresses output of all functions called as follows:
    with suppress_stdout():
        functioncall()
    source: http://thesmithfam.org/blog/2012/10/25/temporarily-suppress-console-output-in-python/
    """
    with open(os.devnull, "w") as devnull:
        old_stdout = sys.stdout
        sys.stdout = devnull
        try:
            yield
        finally:
            sys.stdout = old_stdout


class TemporaryDirectory(object):
    """Create and return a temporary directory.  This has the same
    behavior as mkdtemp but can be used as a context manager.  For
    example:

        with TemporaryDirectory() as tmpdir:
            ...

    Upon exiting the context, the directory and everything contained
    in it are removed.
    """

    def __init__(self, suffix="", prefix="tmp", dir=None):
        self._closed = False
        self.name = None # Handle mkdtemp raising an exception
        self.name = mkdtemp(suffix, prefix, dir)

    def __repr__(self):
        return "<{} {!r}>".format(self.__class__.__name__, self.name)

    def __enter__(self):
        return self.name

    def cleanup(self, _warn=False):
        if self.name and not self._closed:
            try:
                self._rmtree(self.name)
            except (TypeError, AttributeError) as ex:
                # Issue #10188: Emit a warning on stderr
                # if the directory could not be cleaned
                # up due to missing globals
                if "None" not in str(ex):
                    raise
                print("ERROR: {!r} while cleaning up {!r}".format(ex, self,),
                      file=_sys.stderr)
                return
            self._closed = True
            if _warn:
                self._warn("Implicitly cleaning up {!r}".format(self),
                           ResourceWarning)

    def __exit__(self, exc, value, tb):
        self.cleanup()

    def __del__(self):
        # Issue a ResourceWarning if implicit cleanup needed
        self.cleanup(_warn=True)

    # XXX (ncoghlan): The following code attempts to make
    # this class tolerant of the module nulling out process
    # that happens during CPython interpreter shutdown
    # Alas, it doesn't actually manage it. See issue #10188
    _listdir = staticmethod(_os.listdir)
    _path_join = staticmethod(_os.path.join)
    _isdir = staticmethod(_os.path.isdir)
    _islink = staticmethod(_os.path.islink)
    _remove = staticmethod(_os.remove)
    _rmdir = staticmethod(_os.rmdir)
    _warn = _warnings.warn

    def _rmtree(self, path):
        # Essentially a stripped down version of shutil.rmtree.  We can't
        # use globals because they may be None'ed out at shutdown.
        for name in self._listdir(path):
            fullname = self._path_join(path, name)
            try:
                isdir = self._isdir(fullname) and not self._islink(fullname)
            except OSError:
                isdir = False
            if isdir:
                self._rmtree(fullname)
            else:
                try:
                    self._remove(fullname)
                except OSError:
                    pass
        try:
            self._rmdir(path)
        except OSError:
            pass


def help(thing):
    """ Create and show HTML page of module documentation,
    It should accept anything that the regular help() accepts.
    """

    # Create temporary directory to store documentation in
    with TemporaryDirectory() as temp_folder:
        orignal_cwd = os.getcwd()

        # Change working directory to temporary folder
        os.chdir(temp_folder)

        # Create HTML page of doc
        object, name = pydoc.resolve(thing)
        pydoc.writedoc(thing)
        with suppress_stdout():
            filepath = os.path.join(temp_folder, name + ".html")

        # Reset working directory
        os.chdir(orignal_cwd)

        # Open default program to view HTML files
        webbrowser.open_new(filepath)

        # Sleep for 2 seconds so browser can open before deleting file
        time.sleep(2)

if __name__ == "__main__":
    help(os)

Answer 2

Я написал короткую функцию, которая принимает строку, содержащую имя модуля, которая создает html-файл с использованием pydoc и показывает его в браузере по умолчанию.

Он не настраивает веб-сервер, а просто загружает файл в веб-браузер.

import subprocess
import os
import tempfile
import sys
import time

def show_help(module):
    """ Create and show HTML page of module documentation 

        Pass module as a string
    """

    # Create temporary directory to store documentation in
    with tempfile.TemporaryDirectory() as temp_folder:
        orignal_cwd = os.getcwd()

        # Change working directory to temporary folder
        os.chdir(temp_folder)

        # Create HTML page of doc
        subprocess.call(["pydoc", "-w", module], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)       

        filepath = os.path.join(temp_folder, module + ".html")

        # Reset working directory
        os.chdir(orignal_cwd)

        # Open default program to view HTML files
        if sys.platform.startswith('darwin'):
            subprocess.call(('open', filepath), stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
        elif os.name == 'nt':
            os.startfile(filepath)
        elif os.name == 'posix':
            subprocess.call(('xdg-open', filepath), stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

        # Sleep for 2 seconds so browser can open before deleting file
        time.sleep(2)

Я протестировал его с python3.4 на Linux, где он работает нормально, но я не проверял это с Windows.

Вы можете импортировать его как модуль в интерпретаторе, а затем просто использовать show_help("module name") для просмотра документации, где "имя модуля" - это имя модуля в виде строки. Такие как show_help("os"),

Answer 3

Ты можешь использовать pydoc.render_doc создать html файл.

import pydoc
str_help = pydoc.render_doc(str)
with open("str_doc.html", "w") as doc_file:
    doc_file.write(str_help)

Затем вы можете открыть этот файл в веб-браузере:

import webbrowser
webbrowser.open("file:///path/to/your/doc_file.html")