اضبط عرض الغلاف لمستندات Python في محطة

Question

أنا أستخدم قذيفة Python في محطة Tty ، ومن المزعج للغاية أن تلتف جميع الوثائق بعرض ضيق. شاشتي 1600 × 900 بكسل ، مع محطة بلدي في 200 × 56 حرفًا ، لكن وثائق بيثون من القشرة تصر على الالتفاف بعرض أضيق بكثير. (الخطوط التي أدخلها في المطالبة ليست محدودة ؛ فهي تتيح لهم تشغيل عرض ملء الشاشة.)

أنا يقظ لذلك PEP-8 الحد الأقصى لطول الخط يحدد أن docstrings تقتصر على 72 حرفًا لكل سطر ، ولكن هل هناك طريقة لجعلها تستخدم المحطة بأكملها على أي حال؟ أعلم أن Javadoc يزيل خطًا إضافيًا من تعليقات Javadoc ؛ أنا بعد شيء يعمل من هذا القبيل إلى حد ما.

المشكلة الأكبر في ذلك هي قائمة الوحدات النمطية: بدلاً من استخدام العرض الكامل لشاشتي عندما يسرد جميع أسماء الوحدات ، فإنه يستخدم فقط عرض الالتفاف الضيق ، ويعرض الوحدات في أربعة أعمدة فقط ، وبالتالي لا يمكنه في الواقع لا يمكنه في الواقع قم بتناسب القائمة بأكملها على شاشتي (على الرغم من أنها تتناسب تمامًا مع الشاشات الأخرى). لا أستطيع فقط أن تنشرها less إما ، كما أفعل مع الحجم الكبير --help نص في باش.

Answer 1

== تحرير == محدث

لذا فإن المشكلة التي ستواجهها هي أنه بالنسبة للمساعدة المستندة إلى CLI ، فإن عرض سلسلة المستند محدود حقًا فقط من قبل الخطوط الجديدة في الوثائق الأصلية. وهذا يعني ، عند تشغيل "المساعدة" (مستقبل) '، إنه يطبع سلسلة المستند وصفحاتها. لا شيء يتوهم ، لا تنسيق على الطيران. هذا هو السبب إذا قمت بتقديم المستند إلى HTML ، فيمكنك تعديل عرض المتصفح وسوف يلف بشكل مختلف.

الطريقة الوحيدة التي وجدتها لتعديل هذا السلوك هي إذا قمت بالفعل بتعديل Docstring نفسه.

فيما يلي مثال سريع على كيفية قرد الأوتار المستند. في الأساس في docstring ، يتم ترميز الخطوط الجديدة إلى نهاية الخط ، من هذا القبيل

a = """
one
two

three
"""

يشفر إلى

'\none\ntwo\n\nthree\n'

إذا كنت تريد خط "التفاف" تلقائيًا ، فأنت بحاجة فقط إلى استبدال n [^ n] (أي حرف جديد + ليس خطًا جديدًا) مع الحرف الذي تم التقاطه.

re.sub('\n([^\n])', ' \g<1>', a)

ثم يصبح

' one two\n three\n'

هذه طريقة خارقة للغاية لفعل الأشياء ، لكن الطريقة الوحيدة التي يمكنني التفكير بها في إعادة صياغة الأشياء بحيث تتفوق.

مثال أفضل هو:

#!/usr/bin/python

import pydoc
import re

t = re.sub('\n([^\n])', ' \g<1>', pydoc.__doc__)
pydoc.__doc__ = t
help(pydoc)

== تحرير ==

قد يناسب هذا أو لا يناسب احتياجاتك ، لكن كان لدي جذب مماثل قمت بحله بشكل مختلف قليلاً. كتبت غلاف "مساعدة" يحمل مستندات stdlib في متصفح في الخلفية. قد يساعدك أو لا يساعدك - شيء واحد لطيف هو أن إخراج HTML لأشياء PYDOC يسمح بعرض متغير على الفقرات.

يمكنك أخذ البرنامج النصي المرفق ، واستيراده من site.py ، ثم عند تشغيل Help () من CLI على أي أشياء stdlib ، سيفتح صفحة الويب المقابلة تلقائيًا. هذا لا يفعل أي شيء لأشياءك المحلية (لا أعتقد ، لقد مر وقت) ، ولكن يمكن تعديله للقيام بذلك.

إذا كنت شابًا متشابهًا ، فإن الاعتذار. ولكن عند مواجهة جذب مماثل فيما يتعلق بإخراج الأشياء ، هذا ما جربته في البداية.

#!/usr/bin/python

import inspect
import os
import sys
import webbrowser
from pydoc import Helper

__all__ = ['MyHelper', 'old_help', 'help']


class MyHelper(Helper):

    def __init__(self):
        Helper.__init__(self)

    def getdocloc(self, object):
        global old_help
        """Return the location of module docs or None"""
        try:
            file = inspect.getabsfile(object)
        except TypeError:
            file = '(built-in)'

        docloc = os.environ.get("PYTHONDOCS", "http://docs.python.org/library")
        basedir = os.path.join(sys.exec_prefix, "lib", "python"+sys.version[0:3])
        BUILTINS_LIST = ( 'errno', 'exceptions', 'gc', 'imp', 'marshal', 'posix', 'signal', 'sys', 'thread', 'zipimport')
        if (isinstance(object, type(os)) and (object.__name__ in BUILTINS_LIST or file.startswith(basedir)) and object.__name__ not in ('xml.etree', 'test.pydoc_mod')):
            if docloc.startswith("http://"):
                docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__)
            else:
                docloc = os.path.join(docloc, object.__name__ + ".html")
        else:
            docloc = None
        return docloc

    def __repr__(self):
        global old_help
        if inspect.stack()[1][3] == '?':
            return self()
            return ''
        else:
            return '<HHhelp instance>'

    def help(self, *args):
        print args
        global old_help
        if isinstance(args[0], object):
            docloc = self.getdocloc(args[0])
            print '********',docloc,type(docloc)
            if isinstance(docloc, str):
                if docloc.find('http://') == 0:
                    webbrowser.open(docloc)
        else: 
            old_help(args)

global old_help, help
old_help = help
help = MyHelper()

الحل الثاني الذي أستخدمه للحصول على مستندات Python الجميلة هو استخدام Sphinx's sphinx-apidoc لإنشاء مستندات API تلقائيًا لوحدات Python. إن مواد إخراج Doc القياسية Python محددة حقًا (كما تواجه).

ومع ذلك ، مع ذلك - أراهن أن عرض المستندات قابل للتكوين بطريقة أو بأخرى ولكنه سيتطلب ترقيع القرد ... سأقوم بالتجول قليلاً وأرى ما يمكنني العثور عليه.