diff --git a/_images/sphinx_awesome.png b/_images/sphinx_awesome.png new file mode 100644 index 0000000..c088c02 Binary files /dev/null and b/_images/sphinx_awesome.png differ diff --git a/_images/sphinx_cool.png b/_images/sphinx_cool.png new file mode 100644 index 0000000..f738bcd Binary files /dev/null and b/_images/sphinx_cool.png differ diff --git a/_images/sphinx_logo.jpg b/_images/sphinx_logo.jpg new file mode 100644 index 0000000..b38db8d Binary files /dev/null and b/_images/sphinx_logo.jpg differ diff --git a/_images/sphinx_sample.png b/_images/sphinx_sample.png new file mode 100644 index 0000000..dd3be5d Binary files /dev/null and b/_images/sphinx_sample.png differ diff --git a/_images/sphinx_source_automodule.png b/_images/sphinx_source_automodule.png new file mode 100644 index 0000000..9c37e8c Binary files /dev/null and b/_images/sphinx_source_automodule.png differ diff --git a/_images/sphinx_updated_about.png b/_images/sphinx_updated_about.png new file mode 100644 index 0000000..e6f7945 Binary files /dev/null and b/_images/sphinx_updated_about.png differ diff --git a/_images/sphinx_updated_index.png b/_images/sphinx_updated_index.png new file mode 100644 index 0000000..fb51a88 Binary files /dev/null and b/_images/sphinx_updated_index.png differ diff --git a/sphinx.html b/sphinx.html new file mode 100644 index 0000000..7cf00a8 --- /dev/null +++ b/sphinx.html @@ -0,0 +1,476 @@ + + + + + + Documentando Projetos Python com Sphinx + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

+ Documentando Projetos Python com Sphinx +

+
+
+ +
+
+

Sobre Sphinx

+ +
    +
  • Ferramenta oficial de documentação de projetos Python
    • +
  • Usa reStructuredText por padrão
    • +
  • Arquitetura de plugins
    • +
  • Especificamente para Python, consegue extrair a documentação de + dentro de docstrings
    • +
+
+
+ +
+
+

reStructuredText

+

Títulos

+ +

Abaixo do texto, p.ex.

+ + 
Título
+######
+ +

+ O caracter define o nível do tíulo. Depois de + #, vem *, =, + -, ^ e + ". +

+
+ +
+

reStructuredText

+

Markup

+ +

Um *asterísco* para itálico.

+

Dois **asteríscos** para negrito.

+

Duas ``crases`` para código.

+
+ +
+

reStructuredText

+

Listas

+ +

* no começo da linha para bullets.

+ + 
* Listas podem ter
+  mais de uma linha.
+
+ +
+

reStructuredText

+

Listas

+ +

Um número ou # seguido de ponto para uma lista numerada.

+ + 
1. Item 1.
+2. Item 2.
+
+ +
+

reStructuredText

+

Listas

+ +

Para sublistas, basta identar.

+ + 
* Item 1
+   * Item 1.1
+   * Item 1.2
+* Item 2
+
+ +
+

reStructuredText

+ +

+ E ainda: + +

    +
  • Tabelas!
    • +
  • Citações!
    • +
  • Listas de definições!
    • +
  • COMMANDOS ESPECIAIS!
    • +
+

+
+
+ +
+
+

Sphinx

+ +

Certifique-se que Sphinx está instalado no virtualenv ativo.

+ +

É bobo falar isso, mas é que ele não surge do nada.

+
+ +
+

Sphinx

+ +

Primeira vez? sphinx-quickstart docs

+ +

Responda o wizard.

+ +

+ Importante:
+ > autodoc: automatically insert docstrings from modules (y/n) [n]: y +

+ +

+ (Se você esqueceu disso, é possível editar o arquivo de configuração depois.) +

+
+ +
+

Sphinx

+ + 
|-- Makefile
+|-- build
+`-- source
+    |-- _static
+    |-- _templates
+    |-- conf.py
+    `-- index.rst
+
+ +
+

Sphinx

+ + 
Welcome to THE PROJECT!'s documentation!
+========================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+ +
+

Sphinx

+ +

+ make html +

+
+ +
+

Sphinx

+ +

+ +

+
+ +
+

Sphinx

+ + source/about.rst + + 
About the project
+#################
+
+*PROJECT!* is a **SUPER AWESOME** project.
+
+Believe us!
+
+ +
+

Sphinx

+ +

+ make html +

+ +

+ checking consistency... /private/tmp/docs/source/about.rst:: WARNING: document isn't included in any toctree +

+
+ +
+

Sphinx

+ + source/index.rst + + 
Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+
+ +
+

Sphinx

+ + +
+ +
+

Sphinx

+ + +
+
+ +
+
+

CADÊ O PYTHON?

+
+ +
+

Autodoc

+ +

Lembra do

+

> autodoc: automatically insert docstrings from modules (y/n) [n]: y

+

?

+
+ +
+

Autodoc

+ +

source.py

+ +

+ 

#!/usr/bin/env python
+# -*- encoding: utf-8 -*-
+
+"""This is a SUPER MODULE of the PROJECT! project."""
+
+
+def awesome():
+    """AWESOME function."""
+    return 'AWESOME!'
+

+
+ +
+

Autodoc

+ + source/source.rst + + 
THE SOURCE
+##########
+
+.. autofunction:: source.awesome
+
+ +
+

Autodoc

+ +

source/conf.py <- configuração do Sphinx

+ + 
# 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'))
+ +

IMPORTANTE!

+

É relativo ao conf.py, não do diretório do make.

+
+ +
+

Autodoc

+ + +
+ +
+

Autodoc

+ +

source.py

+ +

+ 

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)
+

+
+ +
+

Autodoc

+ +

source/source.rst

+ + 
THE SOURCE
+##########
+
+.. autofunction:: source.awesome
+.. autofunction:: source.cool
+
+ +
+

Autodoc

+ + +
+ +
+

Autodoc

+ +

... peraí...

+ +

Cadê a documentação do módulo?

+
+ +
+

Autodoc

+ +

source/source.rst

+ +

+ 

THE SOURCE
+##########
+
+.. .. autofunction:: source.awesome
+.. .. autofunction:: source.cool
+
+.. automodule:: source
+   :members:
+

+
+ +
+

Autodoc

+ + +
+ +
+

Autodoc

+ +
    +
  • autoclass: documentação da classe inteira.
    • +
  • :members:: contém a lista de membros a serem listados, none = tudo.
    • +
  • :undoc-members:: usado com :members:, remove itens individuais da lista.
    • +
+
+
+ +
+
+

Perguntas?

+
+
+
+
+ + + + + + + +