في أبو الهول ، هل يمكنني تسجيل مجموعة من الكلمات الرئيسية التي يجب ترجمتها دائمًا إلى روابط؟

Question

تحتوي سلاسل المستندات على إشارات إلى فصول Python الأخرى التي حددتها. في كل مرة يواجه فيها Sphinx إحدى هذه الفصول ، أريد أن تدخل رابطًا إلى الوثائق الخاصة بتلك الفئة الأخرى. هل هذا ممكن في أبو الهول؟

على وجه التحديد ، لدي سلسلة مستند مثل:

'''This class contains a bunch of Foo objects'''

يمكنني الكتابة:

'''This class contains a bunch of :class:`~foo.Foo` objects'''

لكني أفضل أن تجد أبو الهول كل مطابقة النص Foo ويجعل الأمر يبدو كما لو أنني كتبت: الفصل:~foo.Foo

Answer 1

يمكنك استخدام وحدات الماكرو.

في مشروعي ، لدي ملف رأس يحتوي على جميع الفصول "المهمة" والوظائف العالمية واختصارها. خطان مثال:

.. |PostItem| replace:: :class:`PostItem <hklib.PostItem>`
.. |PostNotFoundError| replace:: :class:`PostNotFoundError <hklib.PostNotFoundError>`

في rst الملفات ، أقوم بتضمين ملف الرأس هذا. ثم يمكنني استخدام وحدات الماكرو في أي rst ملف:

.. include:: defs.hrst

|PostItem| is a nice class. |PostNotFoundError|, on the other hand is not.

(يمكنك تضمين docstrings من ملفات مصدر Python أيضًا ، باستخدام autogen تمديد. سيتم استبدال وحدات الماكرو في تلك.)

حول مثالك: أود أن أضيف Foo إلى ملف الرأس واكتب docstring بهذه الطريقة:

'''This class contains a bunch of |Foo| objects'''

Answer 2

لدى Sphinx عددًا كبيرًا من أدوار النص المفسرة لهذا.

http://sphinx.pocoo.org/markup/inline.html#cross-referencing-python-objects

أرغب في إدخال فو وأتورطها في تفسيرها كما لو كنت قد كتبت: الفصل:~foo.Foo

هذا يبدو غير عملي. يبدو أنه سيشلل في محاولة تحليل النص الخاص بك. تبحث عن النص المفسر والقواعد القليلة الاقتباس التي تدعمها RST (*_|`) حول الحد العملي.

ما تطلبه قد يؤدي إلى أخذ RST طوال اليوم للتحقق من كل مثيل Foo في كل سياق ممكن وسبب ما إذا كنت تريد رابطًا أم لا. كنت تريد هذا فقط في حالات خلاف ذلك Foo; ؛ البحث التافلي والاستبدال لن يعمل.

يمكنك العبث مع المعالجة المسبقة.

http://sphinx.pocoo.org/ext/autodoc.html#docstring-preprocessing

قد يتيح لك ذلك تجربة استراتيجية عالمية للبحث والاستبدال على نص Docstring الخاص بك.