Python docstrings для Github README.md

Как перекодировать строки python doc в Github readme.md?

Несмотря на то, что это похоже на то, что все делают, я не могу найти достойное решение, и я предполагаю, что это должно быть легко, поэтому кажется маловероятным, что люди собираются бросить два конвертера...

Что я пробовал

pydoc На самом деле просто. Выход pydoc - это manpages (формат groff для UNIX-систем). Который является тупиком, поскольку человек к md - это не вещь. Через HTML, pydoc3 -w + pandoc, полностью помещает docstrings в биты.

пользовательский код. Кажется, есть много коротких пользовательских кодов, но для тех немногих, которые я пробовал, выход не кажется таким же хорошим, как у pydoc, который имеет сводку, добавляет унаследованные методы и перечисляет некоторые атрибуты.

mkdocs. Это было предложено где-то. Это просто загрязняет мою папку, поскольку это вводящее в заблуждение имя, так как это не docstrings > md converter, а md > html.

Sphinx + Pandoc. После исправления проблемы с UTF-8 я отказался от Sphinx, так как у меня есть один py script для конвертирования, а параметр autodoc для quickstart не анализировал мой script. Я попытался в Python импортировать sphinx.ext.autodoc, но TBH документация была слишком длинной, и я сдался.

NB

Существует вопрос [годовой вопрос без ответа SO]] (Автоматически создавать документацию Witiki GitHub от Docstrings Python) по этой теме, но я надеюсь, что, давая много подробнее Я получу ответ.

Ответ 1

У меня есть немного кода, который я использую для создания индексного файла из проекта. Это не совсем то, что вы ищете, но с небольшим завихрением вы можете добавить инструкцию if для файлов py (где у меня есть только html и png) и захватить doc= "ваш DocStrings."... https://gist.github.com/Krewn/6e9acdadddb4bf2a56c0

# WARNING RUNNING THIS FILE WILL OVERIDE EXISTING readme.md FILE IN CWD

import os

class indexer:
    path = "~"
    username = "" # !!! Enter your github username in the provided quotes.
    site = "http://"+username+".github.io"
    proj = ""     # !!! Enter your repository name in provided quotes.
    prod = []
    loc=[]

    def __init__(self,p):
        self.path=p
    def fprep(self,name):
        name.replace(".","")
        name.replace("\\","/")
        return(name)
    def refPrep(self):
        ref = self.site+"/"+self.proj
        for qw in self.loc:
            ref+="/"+qw
        return(ref)
    def HtmlFrek(self,adir):
        self.loc.append(adir)
        os.chdir(adir)
        pys = [f for f in os.listdir('.') if os.path.isfile(f) and f.split(".")[len(f.split("."))-1]=="py"]
        for i in pys:
            Open the file i get the __doc__ string and append it to ret
        for k in folders:
            if(k.__contains__(".")):
                continue
            ret+=self.HtmlFrek(k)
        os.chdir("..")
        del self.loc[len(self.loc)-1]
        return(ret)

    def HtmlProd(self):
        ret = ""
        pys = [f for f in os.listdir('.') if os.path.isfile(f) and f.split(".")[len(f.split("."))-1]=="py"]
        for i in pys:
            Open the file i get the __doc__ string and append it to ret
        folders = [f for f in os.listdir(".") if not os.path.isfile(f)]
        for k in folders:
            if(k.__contains__(".")):
                continue
            ret+=self.HtmlFrek(k)
        self.prod = ret
        return(ret)

i = indexer(".")
q=i.HtmlProd()
#print i.prod

w = open("readme.md","w")
w.write(q)
w.close()

Ответ 2

Я нашел несколько других вариантов для этого:

https://github.com/coldfix/doc2md

Маленький удобный инструмент для извлечения docstrings из модуля или класса и преобразования их в GitHub Flavored Markdown. Его цель - быстро генерировать файлы README.md для небольших проектов.

https://github.com/freeman-lab/myopts

Этот модуль предоставляет инструмент командной строки для разбора файла Python и создания красивой маркировки с вашими определениями функций. Он очень упрямый и жесткий! Но также чрезвычайно прост в использовании.