You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
481 lines
11 KiB
481 lines
11 KiB
<!doctype html> |
|
<html lang="en"> |
|
<head> |
|
<meta charset="utf-8"> |
|
|
|
<title>Documentando Projetos Python com Sphinx</title> |
|
|
|
<meta name="description" content="Colocando uma aplicação Flask em produção em 40 minutos (ou menos)"> |
|
<meta name="author" content="Julio Biason"> |
|
|
|
<meta name="apple-mobile-web-app-capable" content="yes"> |
|
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent"> |
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui"> |
|
|
|
<link rel="stylesheet" href="reveal.js/css/reveal.css"> |
|
<link rel="stylesheet" href="reveal.js/css/theme/night.css" id="theme"> |
|
|
|
<!-- Code syntax highlighting --> |
|
<link rel="stylesheet" href="reveal.js/lib/css/zenburn.css"> |
|
|
|
<!-- Printing and PDF exports --> |
|
<script> |
|
var link = document.createElement( 'link' ); |
|
link.rel = 'stylesheet'; |
|
link.type = 'text/css'; |
|
link.href = window.location.search.match( /print-pdf/gi ) ? 'css/print/pdf.css' : 'css/print/paper.css'; |
|
document.getElementsByTagName( 'head' )[0].appendChild( link ); |
|
</script> |
|
|
|
<!--[if lt IE 9]> |
|
<script src="lib/js/html5shiv.js"></script> |
|
<![endif]--> |
|
|
|
<style type="text/css" media="screen"> |
|
.happy { |
|
color: yellow; |
|
} |
|
|
|
.reveal section img { |
|
border: none; |
|
} |
|
|
|
.reveal ul.empty { |
|
list-style: none outside; |
|
} |
|
|
|
li { |
|
display: block; |
|
} |
|
|
|
.cursor { |
|
background-color: #666; |
|
color: white; |
|
} |
|
|
|
img { |
|
max-height: 90%; |
|
} |
|
|
|
td.seen { |
|
font-style: italic; |
|
font-weight: bold; |
|
} |
|
</style> |
|
</head> |
|
|
|
<body> |
|
<div class="reveal"> |
|
<div class="slides"> |
|
<section> |
|
<section data-background="_images/sphinx_logo.jpg" data-header> |
|
<h1 class="semi-opaque"> |
|
Documentando Projetos Python com Sphinx |
|
</h1> |
|
</section> |
|
</section> |
|
|
|
<section> |
|
<section> |
|
<h2>Sobre Sphinx</h2> |
|
|
|
<ul> |
|
<li>Ferramenta oficial de documentação de projetos Python</li> |
|
<li>Usa reStructuredText por padrão</li> |
|
<li>Arquitetura de plugins</li> |
|
<li>Especificamente para Python, consegue extrair a documentação de |
|
dentro de docstrings</li> |
|
</ul> |
|
</section> |
|
</section> |
|
|
|
<section> |
|
<section> |
|
<h2>reStructuredText</h2> |
|
<h3>Títulos</h3> |
|
|
|
<p>Abaixo do texto, p.ex.</p> |
|
|
|
<pre><code>Título |
|
######</code></pre> |
|
|
|
<p> |
|
O caracter define o nível do tíulo. Depois de |
|
<code>#</code>, vem <code>*</code>, <code>=</code>, |
|
<code>-</code>, <code>^</code> e |
|
<code>"</code>. |
|
</p> |
|
</section> |
|
|
|
<section> |
|
<h2>reStructuredText</h2> |
|
<h3>Markup</h3> |
|
|
|
<p>Um *asterísco* para <i>itálico</i>.</p> |
|
<p>Dois **asteríscos** para <strong>negrito</strong>.</p> |
|
<p>Duas ``crases`` para <code>código</code>.</p> |
|
</section> |
|
|
|
<section> |
|
<h2>reStructuredText</h2> |
|
<h3>Listas</h3> |
|
|
|
<p><code>*</code> no começo da linha para bullets.</p> |
|
|
|
<pre><code>* Listas podem ter |
|
mais de uma linha.</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>reStructuredText</h2> |
|
<h3>Listas</h3> |
|
|
|
<p>Um número ou <code>#</code> seguido de ponto para uma lista numerada.</p> |
|
|
|
<pre><code>1. Item 1. |
|
2. Item 2.</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>reStructuredText</h2> |
|
<h3>Listas</h3> |
|
|
|
<p>Para sublistas, basta identar.</p> |
|
|
|
<pre><code>* Item 1 |
|
* Item 1.1 |
|
* Item 1.2 |
|
* Item 2</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>reStructuredText</h2> |
|
|
|
<p> |
|
E ainda: |
|
|
|
<ul> |
|
<li>Tabelas!</li> |
|
<li>Citações!</li> |
|
<li>Listas de definições!</li> |
|
<li class="fragment">COMMANDOS ESPECIAIS!</li> |
|
</ul> |
|
</p> |
|
</section> |
|
</section> |
|
|
|
<section> |
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<p>Certifique-se que Sphinx está instalado no virtualenv ativo.</p> |
|
|
|
<p class="fragment">É bobo falar isso, mas é que ele não surge do nada.</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<p>Primeira vez? <code>sphinx-quickstart docs</code></p> |
|
|
|
<p class="fragment">Responda o wizard.</p> |
|
|
|
<p class="fragment"> |
|
Importante:<br/> |
|
<code>> autodoc: automatically insert docstrings from modules (y/n) [n]: y</code> |
|
</p> |
|
|
|
<p class="fragment"> |
|
(Se você esqueceu disso, é possível editar o arquivo de configuração depois.) |
|
</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<pre><code>|-- Makefile |
|
|-- build |
|
`-- source |
|
|-- _static |
|
|-- _templates |
|
|-- conf.py |
|
`-- index.rst</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<pre><code>Welcome to THE PROJECT!'s documentation! |
|
======================================== |
|
|
|
Contents: |
|
|
|
.. toctree:: |
|
:maxdepth: 2 |
|
|
|
|
|
|
|
Indices and tables |
|
================== |
|
|
|
* :ref:`genindex` |
|
* :ref:`modindex` |
|
* :ref:`search`</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<p> |
|
<code>make html</code> |
|
</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<p> |
|
<img src="_images/sphinx_sample.png" alt=""/> |
|
</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
source/about.rst |
|
|
|
<pre><code>About the project |
|
################# |
|
|
|
*PROJECT!* is a **SUPER AWESOME** project. |
|
|
|
Believe us!</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<p> |
|
<code>make html</code> |
|
</p> |
|
|
|
<p class="fragment"> |
|
<code>checking consistency... /private/tmp/docs/source/about.rst:: WARNING: document isn't included in any toctree</code> |
|
</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
source/index.rst |
|
|
|
<pre><code>Contents: |
|
|
|
.. toctree:: |
|
:maxdepth: 2 |
|
|
|
about</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<img src="_images/sphinx_updated_index.png" alt=""/> |
|
</section> |
|
|
|
<section> |
|
<h2>Sphinx</h2> |
|
|
|
<img src="_images/sphinx_updated_about.png" alt=""/> |
|
</section> |
|
</section> |
|
|
|
<section> |
|
<section> |
|
<h1>CADÊ O PYTHON?</h1> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<p>Lembra do</p> |
|
<p><code>> autodoc: automatically insert docstrings from modules (y/n) [n]: y</code></p> |
|
<p>?</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<p>source.py</p> |
|
|
|
<p> |
|
<pre><code>#!/usr/bin/env python |
|
# -*- encoding: utf-8 -*- |
|
|
|
"""This is a SUPER MODULE of the PROJECT! project.""" |
|
|
|
|
|
def awesome(): |
|
"""AWESOME function.""" |
|
return 'AWESOME!'</code></pre> |
|
</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
source/source.rst |
|
|
|
<pre><code>THE SOURCE |
|
########## |
|
|
|
.. autofunction:: source.awesome</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<p>source/conf.py <span class="fragment"><- configuração do Sphinx</span></p> |
|
|
|
<pre class='fragment'><code># If extensions (or modules to document with autodoc) are in another directory, |
|
# add these directories to sys.path here. If the directory is relative to the |
|
# documentation root, use os.path.abspath to make it absolute, like shown here. |
|
sys.path.insert(0, os.path.abspath('../../src'))</code></pre> |
|
|
|
<p class="fragment">IMPORTANTE!</p> |
|
<p class="fragment">É relativo ao <code>conf.py</code>, não do diretório do <code>make</code>.</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<img src="_images/sphinx_awesome.png" alt=""/> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<p>source.py</p> |
|
|
|
<p> |
|
<pre><code>def cool(name, awesomeness_level=100): |
|
"""Just a cool function. |
|
|
|
:param str name: The cool person name. |
|
:param awesomeness_level: Their awesomeness level. |
|
:type awesomeness_level: int or None |
|
|
|
:return: A message for the cool person. |
|
:rtype: str |
|
|
|
:raises ValueError: if the awesomeness level is over 9000. |
|
|
|
:note: For true awesomeness, check :py:func:`source.awesome`. |
|
""" |
|
return '{name} is just cool, not awesome'.format(name=name)</code></pre> |
|
</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<p>source/source.rst</p> |
|
|
|
<pre><code>THE SOURCE |
|
########## |
|
|
|
.. autofunction:: source.awesome |
|
.. autofunction:: source.cool</code></pre> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<img src="_images/sphinx_cool.png" alt=""/> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<p>... peraí...</p> |
|
|
|
<p>Cadê a documentação do módulo?</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<p>source/source.rst</p> |
|
|
|
<p> |
|
<pre><code>THE SOURCE |
|
########## |
|
|
|
.. .. autofunction:: source.awesome |
|
.. .. autofunction:: source.cool |
|
|
|
Ok, now you'll see **THE SOURCE**! It's the most freaking *awesome* source in |
|
the whole planet! |
|
|
|
Try no to piss in your pants. |
|
|
|
.. automodule:: source |
|
:members:</code></pre> |
|
</p> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<img src="_images/sphinx_source_automodule.png" alt=""/> |
|
</section> |
|
|
|
<section> |
|
<h2>Autodoc</h2> |
|
|
|
<ul> |
|
<li><code>autoclass</code>: documentação da classe inteira.</li> |
|
<li><code>:members:</code>: contém a lista de membros a serem listados, none = tudo.</li> |
|
<li><code>:undoc-members:</code>: usado com <code>:members:</code>, remove itens individuais da lista.</li> |
|
</ul> |
|
</section> |
|
</section> |
|
|
|
<section data-background='_images/thats-all-folks.jpg'> |
|
<section> |
|
<h1 class="fragment semi-opaque">Perguntas?</h1> |
|
</section> |
|
</section> |
|
</div> |
|
</div> |
|
|
|
<script src="reveal.js/lib/js/head.min.js"></script> |
|
<script src="reveal.js/js/reveal.js"></script> |
|
|
|
<script> |
|
// Full list of configuration options available at: |
|
// https://github.com/hakimel/reveal.js#configuration |
|
Reveal.initialize({ |
|
controls: true, |
|
progress: true, |
|
history: true, |
|
center: true, |
|
// showNotes: true, |
|
|
|
transition: 'slide', // none/fade/slide/convex/concave/zoom |
|
|
|
// Optional reveal.js plugins |
|
dependencies: [ |
|
{ src: 'reveal.js/lib/js/classList.js', condition: function() { return !document.body.classList; } }, |
|
{ src: 'reveal.js/plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } }, |
|
{ src: 'reveal.js/plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } }, |
|
{ src: 'reveal.js/plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } }, |
|
{ src: 'reveal.js/plugin/zoom-js/zoom.js', async: true }, |
|
{ src: 'reveal.js/plugin/notes/notes.js', async: true } |
|
] |
|
}); |
|
</script> |
|
|
|
</body> |
|
</html>
|
|
|