My presentations, using Reveal.js (mostly in Portuguese).
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

<!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="theme/azion.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-tile>
<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>&gt; 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>&gt; 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">&lt;- 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>