api documentation / documentation / documenting / docutils / markdown / markup / python / rest / restructuredtext / sphinx

Qual é a diferença: reST, docutils, sphinx, readthedocs

Isso mudou para: https://www.git-pull.com/code_explorer/rst-docutils-sphinx-readthedocs.html (editado em 2020-06-05, link fixo)

Code Explorer: Viagem através de reST, docutils, sphinx e
extensões.

Para aqueles que projetam temas baseados em reStructuredText, docutils, sphinx
ou qualquer uma de suas dependências, gostaria de economizar seu tempo limpando a
névoa da ambigüidade e vendo o quadro geral.

Isso é de: https://gist.github.com/tony/7287201 . É convertido via
pandoc --from=rst --to=markdown --output=reStructuredText.md reStructuredText.rst.

Objetivo: readthedocs> sphinx> extensions> docutils> reST desempenham um
papel importante na web. Isso inclui sites, documentação e muito mais.
É difícil ter uma percepção concreta do que é o quê sem
mergulhar na fonte e pesquisar.

Começarei com uma visão geral de reStructuredText, docutils e, em seguida,
sphinx e suas extensões.

reStructuredText

Linguagem de marcação ( site da
Docutil sobre reStructuredText ) –
“reStructuredText é um
sistema analisador e sintaxe de marcação de texto simples de fácil leitura, o que você vê é o que você obtém .” [^ 1] É abreviado como
reST, com uma extensão de ..rst

Como o Markdown , a
linguagem de marcação usada em sites como Wikipedia e
GitHub_. Veja outras
linguagens de marcação de documento .

O reST, claro, não se traduz em HTML. Para isso é necessário um
software, vou falar sobre Docutils .

Docutils

Processador – Docutils Homepage –
Docutils é um processador para reST.

Docutils é usado como uma biblioteca por projetos python para sites, livros e
como um componente de software de documentação maior.

A marcação reST é analisada em uma árvore de nós (linguagem de computador), mas
eventualmente em um
gravador .

Um dos escritores que usamos é html4css1.

A saída de qualquer um , especialmente, pode ser personalizada 1. substituindo as folhas de estilo 2. criando uma subclasse.docutils.writerhtml4css1

  1. A substituição das folhas de estilo pode ser vista em
    http://docutils.sourceforge.net/docs/howto/html-stylesheets.html .
    Pelo menos projete de acordo com as regras de
    html4css1.css
    ou personalize com base nisso.

  2. A subclasse pode ser vista no reST parser_ do Github. é um gravador para saída de reST para html. Isso pode exigir a personalização do html4css1.css .
    docutils.writers.html4css1

Para ver exemplos de docutils usados ​​em projetos de software reais, verifique
Docutils in the wild / use cases_, como o site PEP e docutils_
e o reST parser_ do Github.

Docutils: Para designers

Na prática, a maior parte da saída HTML do reST simples será a mesma.
Isso é graças a docutils usando um escritor de HTML consistentemente entediante,
que promete a você, no núcleo, você verá o mesmo HTML e
classes … neste nível.

Internamente, em 99% dos casos, o Docutils usa gera HTML através do mesmo
plugin ( html4css1) deixando grande parte do HTML central, classes e etc.
consistentes.

neste nível? Raramente você fará interface com docutils por
si só / em bruto.

  • Haverá exceções a isso, por exemplo, casos como o analisador reST do Github, algumas personalizações são feitas na saída do ReST padrão. O exemplo: o gravador padrão produz <table>as tabelas [^ 2], portanto, reST os arquivos na visualização do GitHub com uma borda preta . A maneira estranha de corrigir isso era substituir a saída HTML padrão .border=1
  • Sphinx_ baseia-se muito em docutils adicionando novas funções padrão, diretivas (reST e docutils são extensíveis). Veja mais lá.

Esfinge

Documentation Generator ( Sphinx Homepage ) O
Sphinx é usado para construir projetos de documentação. Se docutils é uma
máquina, a esfinge é a fábrica. Um dos muitos geradores de documentação
 .

O Sphinx tem um sistema de temas, oferece suporte a extensões e uma linha de montagem
que permite que os docutils “se conectem” em vários pontos durante o
processo de construção .

Sphinx implementa conceitos em Docutils_, como funções e diretivas em
sua própria maneira. Ele os apresenta em seu próprio sistema de extensão. As
extensões Sphinx podem se conectar a projetos Python em vários momentos, fornecendo de
tudo, desde amplas facelifts até ajustes meticulosamente orientados para o OCD.

Aqui estão alguns projetos do sphinx e suas
versões HTML e PDF correspondentes .

todo flask, python 2.7, python 3, sqlalchemy, projetos não python

Esfinge: para designers

Nota: Por favor, leia Docutils: Para designers_, como sphinx se baseia em
Docutils_ como um componente.

Você está construindo um tema para a
esfinge , tenha em mente:

  1. Tema pelo menos as regras
    html4css1.css
    ou aceite os padrões.

    Deixar algo perdido aqui fará com que o reST padrão apareça
    incorretamente :(.

  2. Tema pelo menos as regras
    basic.css_t
    ou aceite os defaults ( ).@import url("basic.css");

    Para construir sobre os padrões, você pode em seu arquivo. Você pode ver um exemplo disso em pyramid.css_t.@import url("basic.css");
    .css_t

    Um ponto fraco da esfinge, se você viu o arquivo, é que o wtf está indo para onde aqui.basic.css_t

  3. Conheça os modelos padrão e substitua-os se desejar:

    Aqui estão os modelos padrão.
    https://bitbucket.org/birkenfeld/sphinx/src/e5e3a44d334a/sphinx/themes/basic?at=default

  4. Entenda um conceito: existe o CSS do Layout e o CSS do conteúdo.

    O Conteúdo: saída da marcação reST As regras CSS e HTML para
    o conteúdo em docutils e Sphinx são vagas, genéricas e monótonas
    propositalmente. A saída HTML gerada deve ser a mesma. Isso ocorre
    porque as entranhas (o conteúdo gerado pelo reST) não têm
    opiniões.

    O tema da saída de conteúdo do reST é mais parecido com a
    composição tipográfica .

    Em caso de dúvida, você pode herdar padrões de
    basic.css_t
    via no seu arquivo CSS e este por :@import url("basic.css");
    theme.conf

    [theme]
    inherit     = basic
    stylesheet     = yourtheme.css

    ou copie e cole seções onde partes do seu tema parecem sem estilo.

    O Layout: O layout é a camada externa da documentação.
    Dentro dele está o conteúdo. Aqui você está seguro para incorporar
    opções / variáveis ​​de modelo ao
    estilo Jinja2 . É aqui que o design se junta e as coisas ficam normais.

    O HTML envolvendo o tema, o arquivo, as barras laterais, cabeçalhos, etc. O wireframe sendo colocado junto..css_t

Opções para temas dinâmicos / personalizáveis: Sphinx usa porque você pode usar para permitir que variáveis ​​de tema passem para ele. para ser concluído ..css_t
{{ myoption }}

Readthedocs.org

Semelhante: http://pythonhosted.org/ .

readthedocs , também conhecido como rtfd / rtd /
readthedocs.org é um site que fornece documentação para
projetos de software .

Ele constrói e hospeda projetos de documentação do sphinx.

A documentação de cada projeto de software pode ter seus próprios arquivos, extensões sphinx e tema sphinx..rst

FAQ e Misc

Qual é a relação entre readthedocs e sphinx / docutils / reST?

Sphinx usa docutils, docutils usa reST.

O docutils é um “gerador de documentação”?

Eu diria que não. Ele processa
reST . Não precisa
ser documentação.

É uma biblioteca python básica e desempenha um papel fundamental na
comunidade python . Python é código aberto e produto não apenas de sintaxe, mas também de uma
comunidade e mais de uma década de trabalho, PEP ou não. Não haveria
python sem primeiro.

A documentação oficial de Python.org usa Sphinx e, portanto, docutils.
Por mais importantes que sejam os docutils – não fazem parte da biblioteca padrão.

Docutils é grande .
É um projeto que se desenvolve em um ritmo diferente do python principal. Ele pode
ter contribuições para ele sem a necessidade de um problema no
projeto oficial Python (um PEP) ou um patch para a base de código principal
( cpython ).

Docutils in the wild / casos de uso

Implementações de docutils não readthedocs e não sphinx.

Site PEP e docutils

Nota: a pesquisa sobre isso revelou-se anômala em relação ao que eu
esperava. Apesar da fragmentação dos docutils do python, o
próprio docutils possui código relacionado ao PEP em sua própria biblioteca. Todos baixam isso
com a instalação do pacote por algum motivo – embora eles provavelmente
não se importem em escrever PEPs.

Uma proposta de aprimoramento Python (PEP) não é uma documentação. O PEP
site e os sites PEP
fonte está em toda afeta o seu próprio
projeto.

Não usa esfinge. Ele tem sua própria personalização de modelo que é especificada
no PEP 1.

Estou surpreso, docutilstem em seu pacote principal código relacionado ao PEP [2].
Isso significa que cada vez que docutilsé instalado, o código personalizado relacionado aos
processos burocráticos do python também está em nossos projetos.

Como um novo explorador – não estava por perto para ler ou ver como isso aconteceu,
mas vou pesquisar. (veja TODO acima) Mas para um site sagrado como o PEP estar
contradizendo as melhores práticas do python e um módulo contrib para hospedar
código como esse, precisa ser explicado no contexto.

Analisador reST do Github

Embora Markdown seja definitivamente
a “marcação para HTML” mais popular de seu tipo, o GitHub oferece suporte a várias
linguagens de marcação com marcação .

/ lib / github / command / rest2html .
O que é isso? Um analisador reST. E github / markup é ruby. Esta
implementação docutils subclasses e .docutils.writers.html4css1 Writer
HTMLTranslator

Como cuspir o reST?

if __name__ == '__main__':
    sys.stdout.write("%s%s" % (main(), "n"))
    sys.stdout.flush()

/lib/github/markup.rb
(ruby):

def execute(command, target)
  out = ''
  Open3.popen3(command) do |stdin, stdout, _|
    stdin.puts target
    stdin.close
    out = stdout.read
  end
  out.gsub("r", '')
  # <snip>
end

def command(command, regexp, &block)
  command = command.to_s

  if File.exists?(file = File.dirname(__FILE__) + "/commands/#{command}")
    command = file
  end

  add_markup(regexp) do |content|
    rendered = execute(command, content)
    # <snip>
    rendered
  end
end

Não consigo ler ruby, mas parece que
/ lib / github / comandos /
está furado para um nome de arquivo existente e o script
rest2html
é enviado contentdo arquivo. O é passado para o tiro.stdout.read

O importante aqui é
/lib/github/markups.rb ,
onde o comando é transmitido se o regex corresponder ao nome do arquivo.:rest2html
/re?st(.txt)?/

command(:rest2html, /re?st(.txt)?/)

(de
/lib/github/markups.rb#L51
linha 51.)

O GitHub, com o script _rest2html, meio que sai de seu caminho para
deixar o reST feliz. Seu software para marcação é ruby, mas para rest2html
funcionar, seu servidor precisa ter python funcional, docutils e a
carga de uma engrenagem aberta executando python em seu serviço à luz do
dia. Parece sólido, bata na madeira, mas para alguém encarregado da
segurança, adicionar uma nova linguagem desta forma é apenas mais cabelos brancos.

Atualizações

  • 03/11/2013 – Criado.

LICENÇA: http://creativecommons.org/licenses/by-nc-nd/3.0/us/
Copyright: Tony Narlock

[^ 1]: http://docutils.sourceforge.net/rst.html

[^ 2]: http://sourceforge.net/p/docutils/code/7661/tree/trunk/docutils/docutils/writers/html4css1/__init__.py#l1556

Related Posts

Transforme sua coleção de carteiro em documentação html