ありがとうございます前のプレゼンテーションここから撮影してみますか?ありがとうございます誰ですか?まず私を紹介します私の名前はたかいきしみづか日本から来ました3つの作業を行います1つはスフィンクスコーメンテナー2011年から始まります2つはオーガナイススフィンクスJPユーザーグループ日本で3つはメンバーPythonJPコミュニティー私はカンパニーをビープラウドでウェブアプリケーションをビジネスカスタマスジャンゴ、ピラミッド、SQRアクミ、スフィンクス他のPythonリレーション前のプレゼンテーション私はPythonJP20112015年日本でこのオクトーバーのイベントを会いましょうレーションが開催して私たちは日本に来てくださいとにかくAutoDocAutoDocAutoDocはこのセッションの主題ですAutoDocはSourceCodeを生産してAutoDocはDocSlingを使ってアクトヴィネスカスタマスの設定をして多くの人がAutoDocのDocSlingを使って多くの人がAutoDocのAutoDocのAutoDocのほとんど人々が知ってくれます。そして、80回目のレイドラインです。このレイドラインはドクストラインです。ドクストラインはファンクションを使って、ファンクションのファンクションバディのファンクションを使って、ファンクションを使って、パイソンのインタクトシャルを使って、ドクストラインを使って、2つの質問は、APIドクストラインを使って、過去半年に使ってる人も多くの人々が、APIドクストラインで使って、しかし、半分の人は API ドキュメントを使用するために使用されていないと思います。その理由は何でしょうか?例えば、誰かが何かを使用するために使用されていませんか?あるいは、どこかを使用するために使用するために使用されていませんか?あるいは、どこかを使用するために使用されていないといったことがあります。例えば、ドクスチェーンには、そのスタッフでも行为の行為は変化していません。その理由は、それを解決してみます。そのため、ドクスチェーンに対応するために解説するようにしております。このような意味を、Docからパイソンのソースコードの時に出现します。そして、第二つは、 ドクスチェーンを使用するための意味を解説するようにしています。ドックスリングの使い方を紹介しますでは動きましょうスフィンクのオートドッグはドックスリングの使い方を最も利用しています私はドックスリングの使い方を説明していますスフィンクはどのようにセットアップしていますかスフィンクはドキュメンテーションでスフィンクをスフィンクをスフィンクの使い方を説明していますそしてストーリーストーリースフィンクはゲログランドルのスフィンクの父さんです2007年パイソンオフィシャルドキュメントはレテックで書かれていますでもゲログランドルはスフィンクの使い方を変更していますそして2007年スフィンクを使い方はパイソンオフィシャルドキュメントで使い方を説明していますそしてスフィンクを説明していますパイソンオフィシャルドキュメントを説明していますリテックでスフィンクを説明していますまたマグカップを説明していますスフィンクがリリースされていますさらにスフィンクを説明していますそしてNARATIVE DOCKSそうすることがオートメーティーズドッグビルディング、オートメーティーズドッグビルディング、リードザドッグサービスのホストリング。今、このライブライズとツールが使用されています。パイソンスピンク、プラグス、ジジャ2、ジャンゴ、ピラミッツ、SQC、RKM、ナンパイ、サイパイ、サーキュラム、ファブリックス、アンシブル、AWS AI、SELI。今、ナンパイソンライブライズとツールが使用されています。シェフ、KQPHP、マスジャックス、セレニュー、バニッシュ、そう思います。スピンクがオートメーティーズドッグビルディング、スピンク、エクスト、オートドッグ、オートサマリ、ドクテスト、カバイチ。オートドッグは最も重要なフィーチャーです。パイソンのリレーターのライブライズはオートドッグフィーチャーです。このコードのプラグスを使用してみましょう。このライブライズ、このリグサンプルライブライズ、このコードのプラグスを使用してみます。ライブライズの名前はディープソートです。例えば、これがライブライズのストラクターです。ライブライズは3モジュース、API.py、calcul.py、Util.py、2.ボックスは、Util.pyのプラグラムコードのプラグラムを使用してみます。もし、フィンクのインストレーションはありません、このコマンでフィンクのインストレーションを使用してみます。フィンクのインストレーションを使用してみます。フィンクのインス irony on爆 outbreak、1主描われては塩酢外が付属している。2主描かない、1主描かない、1主描かない、2主描かない、1主描かない、1主描かない、1主描かないすくろが出される在序。1主描かない、1主描かない、4主描かない、この将终しながらツンク東さんを使探してみます。スミックスクイックスタッドコミDownを使ってインタビューウィザードが名称されているプロジェクティプロジェクト名前とプロジェクトファイジャンが使えますウィザードも特に質問によるような通常、その順番にエンタキュートを押すタイプが8-2のオプションはこのセッションが大事ですそのため、このハイファイムオプションを使用するために、ハードコーディーのメイクのタゲットを作るために、それがあなたに応援することができます。このオプションについてのプレゼンテーションを説明します。このオプションはスインク1.3を説明します。ハイファイムオプションはスインク1.5のデフォルトを説明します。そのため、HTMLをドックデリクトリーでHTMLアートプットを作るために、HTMLデリクトリーのアートプットを使用するために、これがアートプットの例えです。このデリクトリーのファイルストラクチャーを説明します。ライブラリファイルとデリクトリーを説明します。デリクトリーのアートプットとドックデリクトリーを説明します。スカルフォルトファイルスとドックデリクトリーを説明します。特に、このエローファイルを説明します。では、エローファイルのアートプットとドックデリクトリーでエローファイルを説明します。ステッカーのスピンクをアートデリクトリーのアートプットとドックデリクトリーを説明します。コンフファイルスピンクを説明します。もう一つ、リーダーラインは3と5と2です。3rd line is add your library path to import them from Sphinx Autodoc.Line 5 is add Sphinx X Autodoc to use extension.Next, let's specify the module you want to document.This is add auto module directive to your doc.1st box is utils file that is part of deep thought example library.2nd box is rest file.You can see the auto module usage in this box.Auto module is a Sphinx directive syntax that is provided by Autodoc extension to generate document.This is the 2nd box.Sorry, I can't click.OK.Line 4 is auto module directive import specified module and inspect it.In this case, deepthought.utils module will be imported and be inspected.Line 5 is members option.We inspect all members of module, not only just module.3.OK.We are now all ready.Next, let's invoke makeHTML again.So, as a last result of makeHTML, you can get automatically generated document from .py file, like this.Internally, auto module directive inspects your module and renders function signature arguments and doc strings.How do it work?Auto doc directive generates intermediate rest, like this.Actually, intermediate file is not generated in your file system, just created on memory.If you want to see the intermediate rest of lines, you can use hyphen-vvvv option, like this.Sphinx of equal hyphen-vvvv for makeHTML command line.As you see, auto module directive is replaced with concrete document content, but please take care.Sphinx auto doc import your code to get doc strings.If it means auto doc will execute code at module global level, let me introduce a bad case related to this.This module will remove all your files, and danger.py was designed as a command line script instead of import from other module.If you try to document with using auto doc, data world function will be called by global line. Consequence of this, makeHTML will destroy all your files.On the other hand, saver.py green blocks using execution guard, if I understand the name, equal main.It's a very famous Python idiom, I think.Because of the execution guard, your file will not be removed by makeHTML.The other particular matter, you shouldn't try to document your setup.py for package module for your package with using auto doc.Now, let's return to the doc string and its output.This output lacks necessary information.It is information of the argument.If you are looking for API reference and you find it, you will say, if you find like this library reference, you will say, oh, I can understand the type of argument and meaning even reading this.In this case, you can use info field syntax for describing arguments.Doc strings should have a description for each function argument like this.Please let part a special version of field list syntax that called info field list.The specification of info field list is described as the URL page, this page.Info field list is render as this.The output is quite nice, so you will say, oh, I can understand it, maybe.Cross-reference to functions.You can easily make cross-reference difference from other location to the dump function.Of course, the cross-reference is beyond the page.So far, I introduced the basics of auto doc.The following subject is dedict deviations of the implementation and the document by using doc test.I think good ABA has a good document that illustrates the usages of the API by using a code example.If doc has a code example, you can grasp the API usage quickly and exactly.The code example search for red lines to doc string area is called doc test block.Obviously, this looks like interactive content of the Python interactive shell.Actually, you can copy and paste the red lines from Python interactive shell.After make HTML, you can get syntax highlighted doc test blocks like this.Library users can grasp the API usage quickly and exactly.And also users can try out it easily.And the point of view from library developers.Code example is very close from the implementation.We can expect that a library developer will update code example when the interface is changed by themselves.Really?Sorry, I don't base it.If the code example was very close from implementation, developers wouldn't mind to it.Because developers have no spare time to read the implicit rule from the code.Explicit is better than implicit for us.Okay, let's use doc test builder to detect deviations of implementation and documentation.To use doc test builder, you need to add a Sphinx doc test extension to console.py like this.Add a Sphinx EXO doc test line.With only this, you are ready to use doc test builder.Okay, let's invoke make doc test command.After that, you can see the dumps function will provide us different result from the expected one.Like this.Expected one is spam one ham egg.Actual one is to be implemented strings.That is returned from dumps function.I think it is not implemented properly yet.Anyway, by using the doc test builder, it shows us differences in implementation and sample code in the documentation.Actually, if your unit test also contains doc test, you don't need to do this by Sphinx side.However, if you don't write the unit test yet, make doc test would be a good place to start.Next is listing APIs automatically with using aut summary.As already noted, autodoc is very useful.However, if you have a lot of functions, a lot of modules,you need to prepare many destructed files for each modules.This box is for uts.by.In this case, you should also prepare such.rest files for API modules and calc modules.If you have 100 modules, you should prepare 100 rest files.As you see, each rest files have just four lines.You can guess them by repeating copy and paste and modify it.However, I believe that you don't want to repeat that like this.Don't repeat yourself.Let's use aut summary extension to avoid such boring tasks.Set up Sphinx aut summary extension.This is your.conf.py again.Line 6 to add Sphinx X aut summary to use extension.Line 8 to use members option for each autodoc-related directive.Line 9 to generate rest files.What you will specify with using aut summary directive.You can use aut summary directive in your rest file as you see.This sample uses aut summary directive and the talk tree option.The talk tree option is a directive location of intermediate files that will be generated by aut summary.Content of aut summary directive.divsort.api, calc, and uts.Modules name you want to document.Thereby, the aut summary, you will get 100 intermediate.rest files if you have 100 modules.After that, make HTML command again.After that, make HTML command again.Finally, you can get each documented pages without forcing trouble-less simple operations.Additionally, aut summary directive you wrote was generating table of contents that linking each module's pages like this.That one is discovering undocumented APIs by using coverage extensions.So far, we've automated the autodoc by using aut summary.In addition, now you can also find the deviation of document and implementation by using the doc test.But how do you find a function that is not writing doc strings at all?For such situation, we can use coverage extensions to find undocumented functions, classes, and methods.To use coverage extensions, you should set up coverage extension to conf.py again.Line 7, redline, to add a 6x coverage to use the extension.That's all.Let's make coverage.After that, you can get the result of coverage measurements.The coverage report is recorded in build underscore build slash coverage directory.Under slash build coverage directory have Python.txt file.That contains undocumented functions, classes, and modules.As you see, you can get the undocumented function name if undocumented function is exist.However, please take care that command always returns 0.Make coverage command always return 0.Then, you can't distinguish the presence or absence of the undocumented function by the return code.In my opinion, it's fair enough because coverage command shouldn't fail regardless of whether coverage is perfect or not.However, unfortunately, make coverage also unsupported to generate coverage.xml for Jenkins or someCI tools.As a conclusion of this, you can discover the undocumented functions, but you can't integrate the information to a CI tool.Sorry for inconvenience, and we are waiting for your contribution to solve the problem.Rap up.Let's review the reason for not writing aDocSling that was introduced at the beginning.I don't know what where should I write.Let's write a description argument and doc test block as the next line of function signature.The second is, are there some docSling format specs?Yes, you can use info field list for argument spec, and you can use doc test block for code example.Third one is, it's not beneficial.If you can use autodoc, autosummary, and doc test and coverage, you make it beneficial.I think these reasons are resolved by using Sling's autodoc features until.Let's write a docSling and use autodocs.Finally, at the end, I'd like to introduce some of the tips.First one is options.Options for autodoc. Autodoc have several options like this.Members is to document just specified members.If you specify the option with that parameter, it means all members will be documented.Second one is under doc and hyphen members.It will be to document members which does not have docSling.If you specify the option with that parameter, all undocumented members are rendered.Private members option to document private members and special members option to document special members, like start with double underscore, double underscore name.Inherited members option to document inherited from superclass.By default, Sling does not render inherited members.Just render is defined in that class, exactly.Private refer to Sling's reference for the detail of options.Second one is directives for web API.Sling's control HTTP domain, third party extension provides HTTP domain to generate web API doc.As you see, you can use get directive.Here, HTTP call get directive is used.HTTP domain also provides other HTTP directives, like HTTP call output or date or zone.HTTP syntax highlighter is also provided by Sling's control HTTP domain extension.It generates nice web API reference page and well-organized web API index page, like this.Sling's control HTTP domain generate new index link at the top of Sling's document and the link describes HTTP-related method index.HTTP domain also contains Sling's control.HTTP extension that supports Flask, Bottle, and Tornade web application framework to document web API methods automatically by using reflections.The last one is document translation.You can get translated output with editing restructure text and Python code.For that, you can use make getTekist command that generates getTekist style POT file, like this, and make getTekist extract text from restructure text file and Python source file that references by autodoc.It means you can translate them into any language with relighting the original restructure text file and Python source files.If you are interested in it, please search my Python APAC session in this year on Slideshare. Thanks.Do you have some advices how to deal with a different version of your software when I have a different, without compatibility between versions and I need to version my things document?I'm sorry, I can't, I'm not worried English.Please speak again slowly.OK, so how to deal with the different versions of your documentation?So, autodoc test is composing every time new version and you don't save it in your subversion system or something like this, and I have different compatibility between versions of my software, so do you have some advice or tips how to deal with different versions of your documentation?Sorry, maybe next question.After sessions, please.Thank you.Are there other formats for doc string you're supporting? Or do you recommend the info field method?Other formats?Other formats for doc strings than info field?Other formats?OK.Sphinx recognize doc string format as a restructure text, but Sphinx 1.3 have Napoleon extension that recognize Google style doc string format, then if you want to use that, you can use Sphinx.ex.nappleion extension.You showed that you can document ACTP methods within doc strings.One tool that I'm using is Swagger and one cool thing that it can do is that you can generate clients from it, client code and even interactive websites that you can call the methods.Are you thinking about developing something like that from doc strings because that would be really, really cool.OK.Sphinx extension that's called BlockDiag is exist.Diag3s have block figure or...Sorry, I forgot the name.Sequence Diagram extension.SEQDiag can describe sequence of the flow.Then you want to figure of sequence to using API.You can use SeqDiag.Thank you.Next session here at half past 12.