web-dev-qa-db-ja.com

Python docstrings to Github README.md

python doc文字列をGithubにトランスコードするにはreadme.md？

誰もがしているように思えますが、私はきちんとした解決策を得ることができないようで、それは簡単なはずだと思っています。

私が試したこと

pydoc実際には単純です。 pydocの出力はマンページ（UNIXシステムのgroff形式）です。 mdへの人間は事ではないので、これは行き止まりです。 HTML経由、pydoc3 -w + pandoc、docstringを完全にビットに変換します。

カスタムコード短いカスタムコードがたくさんあるようですが、私が試した少数の人にとって、出力はそのpydocほど良くないようです。概要があり、継承されたメソッドを追加し、いくつかの属性をリストします。

mkdocs。どこかで提案されました。それはdocstrings> mdコンバーターではなく、md> htmlであるので、それは誤解を招く名前であるため、単に私のフォルダーを汚染します。

Sphinx + Pandoc。UTF-8の問題を修正した後、変換する単一のpyスクリプトとautodoc設定があるため、Sphinxをあきらめましたクイックスタートでスクリプトが解析されませんでした。私はPythonをインポートしようとしましたsphinx.ext.autodocしかしTBHドキュメントが長すぎたため、あきらめました。

NB

このトピックには[1年前の未回答のSO質問]（ Python Docstrings からGitHub Wikiドキュメントを自動生成））があり、しかし、私はより多くの詳細を与えることによって私が答えを得ることを願っています。

pythonmarkdownrestructuredtextdocstringmanpage
21
Matteo Ferla

プロジェクトからインデックスファイルを生成するために使用するコードが少しあります。それは正確にあなたが探しているものではありませんが、少し小刻みにpyファイル（私がhtmlとpngしか持っていない場合）にifステートメントを追加して、doc= "your DocStrings。" ... https://Gist.github.com/Krewn/6e9acdadddb4bf2a56c

# 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
kpie

私はこれを行うための他のいくつかのオプションを見つけました：

https://github.com/coldfix/doc2md

モジュールまたはクラスからdocstringを抽出してGitHub Flavored Markdownに変換するための小さな便利なツール。その目的は、小規模なプロジェクトのREADME.mdファイルをすばやく生成することです。

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

このモジュールは、Pythonファイルを解析し、関数定義を使用して見栄えの良いマークダウンを生成するためのコマンドラインツールを提供します。非常に独断的で厳格ですが、使用方法も非常に簡単です。

4
Duncan Lock

他の答えは素晴らしいです。しかし、私（OP）は私が最近していること（Qの1〜2年後）を共有すべきだと思いました。

私はSphinxとそのマークダウン拡張を使用しています。以下を実行します。

Sphinx-markdown-builder

Sphinx-markdown-builder pythonモジュールが必要です。

 pip install sphinx sphinx-markdown-builder;

Sphinxを実行する

Autodocではありません!! apidoc！

sphinx-apidoc -o Sphinx-docs . sphinx-apidoc --full -A 'Matteo Ferla'; cd Sphinx-docs;

会議

次のようにconf.pyファイルを修正するか、以下のechoコマンドを遅延コピーして貼り付けます。

マニュアル

最初に行のコメントを外します
これらは別の方法でコメント化されています！

import os import sys sys.path.insert(0, os.path.abspath('../'))

../への変更に注意してください

奇妙な点の1つは、魔法のメソッドが複雑になることです。これを上書きするには、どこかに追加します。

def skip(app, what, name, obj, would_skip, options):
    if name in ( '__init__',):
        return False
    return would_skip  
def setup(app):
    app.connect('autodoc-skip-member', skip)

注意すべきこと。 docstringsは再構成されたテキストで書かれるべきです。それらがマークダウンにある場合、MODを追加する必要があります this を参照してください。

TL; DR

これをコピーして貼り付け：

echo " import os
import sys
sys.path.insert(0,os.path.abspath('../'))
def skip(app, what, name, obj,would_skip, options):
    if name in ( '__init__',):
        return False
    return would_skip
def setup(app):
    app.connect('autodoc-skip-member', skip)  
 " >> conf.py;

ショータイム

それからショータイムです。

make markdown;

ファイルをコピーして、好きなようにきれいにしてください。

mv _build/markdown/* ../; rm -r Sphinx-docs;
1
Matteo Ferla