Classe WebSupport

class sphinxcontrib.websupport.WebSupport[código fonte]

Classe principal API para suporte pacote. Todas interações com o pacote suporte web devem ocorrer através dessa classe.

Classe usa os seguintes argumentos:

diretorio fonte

O diretório que contém fonte reStructuredText arquivos.

diretório construção

O diretório para construir dados e arquivos estáticos. Deve ser usado quando criar objeto WebSupport que irá ser usado para construir dados.

diretório dados

O diretório de dados para web support. Deve ser usado quando criando objeto WebSupport que irá ser usado para recuperar dados.

buscar

Pode conter uma string (e.g. ‘xapian’) referenciando adaptator intrínseco para usar uma instância de subclasse BaseSearch.

memória

Deve conter a string representando a uri do banco de dados ou instância da subclasse StorageBackend. Se não for informado, novo banco de dados sqlite será criado.

moderation_callback

Chamada para ser usada quando novo comentário adicionado não for exibido. Aceita um argumento: dicionário representando o comentário que foi adicionado.

diretório estático

Se os arquivos estáticos devem ser criados em uma localização diferente e não em '/static', isso deve ser uma string com o nome dessa localização (por exemplo, builddir + '/static_files').

Nota

Se você especificar staticdir, você normalmente desejará ajustar staticroot de acordo.

staticroot

Se os arquivos estáticos não são servidos a partir de '/static', isso deve ser uma string com o nome daquela localização (por exemplo, '/static_files').

docraiz

Se a documentação não é servida do caminho base da URL, deve ser uma string especificando path (ex.. 'docs').

Alterado na versão 1.6: Classe WebSupport foi movida para sphinxcontrib.websupport em sphinx.websupport. Por favor adicionar pacote sphinxcontrib-websupport em suas depêndencias e usar a classe do novo pacote.

Métodos

WebSupport.build()[código fonte]

Construir documentação. Grava dados nos diretórios de saída outdir. Usar como:

support = WebSupport(srcdir, builddir, search='xapian')
support.build()

Isso vai ler arquivos reStructured text do diretório fonte srcdir. Então vai construir índices de pesquisa e pickles, colocando-os em builddir. Também salva dados no banco de dados.

WebSupport.get_document(docname, username='', moderator=False)[código fonte]

Carrega e retorna conjunto de documento. O documento será um objeto dicionário o qual irá renderizar o modelo:

support = WebSupport(datadir=datadir)
support.get_document('index', username, moderator)

Em muitos casos docname irá requisitar caminho e passar diretamente para essa função. Em Flask, isso fica algo como:

@app.route('/<path:docname>')
def index(docname):
    username = g.user.name if g.user else ''
    moderator = g.user.moderator if g.user else False
    try:
        document = support.get_document(docname, username,
                                        moderator)
    except DocumentNotFoundError:
        abort(404)
    render_template('doc.html', document=document)

O dicionário do documento retornado contém os seguintes itens que podem ser usados durante a renderização do modelo.

  • body: O corpo principal do documento como HTML

  • sidebar: A barra lateral do documento como HTML

  • relbal: Div contendo links para documentos relacionados

  • title: O título do documento

  • css: Links para arquivos css files usados pelo Sphinx

  • script: Javascript contendo opções de comentário

Isso aciona DocumentNotFoundError  se um respectivo documento docname não for encontrado.

Parâmetros:

docname – o nome do documento é carregado.

WebSupport.get_data(node_id, username=None, moderator=False)[código fonte]

Obtem os comentários e fonte associado ao node_id. Se username é obtido será incluido nos comentários de retorno. O padrão CommentBackend retorna um dicionário de duas chaves, fonte e comentários. fonte e fonte raw do node e é usado como ponto inical para propôr o que o usuário pode adicionar comentários é uma lista de termos que representam comentário, cada qual com os seguintes itens:

Chave

Conteúdos

text

O texto ou Comentário

nome do usuário

O nome do usuário associado com o comentário

id

O id único do comentário

classific.

A avaliação do comentário atual

tempo

o tempo em segundos desde que o comentário foi adicionado

data

conjunto contendo época da informação. Contém três chaves: ano, mês, dia, hora, minuto, segundo, iso e delta. iso é formato de tempo formato ISO 8601. delta é uma forma de imprimir tempo do comentário (ex. “3 horas atrás”).

votação

Se user_id foi usado, erá ser um inteiro representando o voto. 1 para aumentar voto, -1 para abaixar voto ou 0 se não votado.

node

O id do node ao qual o comentário está associado. Se o comentário pai é outro comentário em vez de um node, isso será nulo.

pai

O id do comentário ao qual este comentário está associado se não estiver associado a um node.

filho

Lista de filhos no formato.

diff_proposta

HTML representando as diferenças entre o fonte atual e o fonte proposto.

Parâmetros:
  • node_id – o id do node para obter comentários.

  • username – o nome do usuário do usuário leitor dos comentários.

  • moderator – onde usuário é um moderador.

WebSupport.add_comment(text, node_id='', parent_id='', displayed=True, username=None, time=None, proposal=None, moderator=False)[código fonte]

Adicionar comentário para um node ou outro comentário. Retorna comentário no mesmo formato como get_comments(). Se o comentário é vinculado a um node, passar o id do node (como string) com o argumento do node:

comment = support.add_comment(text, node_id=node_id)

Se o comentário é filho de outro comentário, fornece id do pai (como string) com argumentos chaves do pai:

comment = support.add_comment(text, parent_id=parent_id)

Se desejar armazenar nome usuário com o comentário, passe argumento opcional username aos argumentos:

comment = support.add_comment(text, node=node_id,
                              username=username)
Parâmetros:
  • parent_id – o id prefixado do comentário pai.

  • text – o texto do comentário

  • displayed – com finalidade de moderação

  • username – o nome usuário que fez o comentário.

  • time – a data quando o comentário foi criado, padrão é agora.

WebSupport.process_vote(comment_id, username, value)[código fonte]

O processo votação usuário. O pacote web configa na API usuário para executar autenticação. A API usuário irá receber tipicamente um comentário_id e o valor de um formulário, certificar-se que o usuário está autenticado. Usuário único deve estar ativo o qual também pode ser usado para recuperar dados votações anteriores. Por exemplo, no Flask:

@app.route('/docs/process_vote', methods=['POST'])
def process_vote():
    if g.user is None:
        abort(401)
    comment_id = request.form.get('comment_id')
    value = request.form.get('value')
    if value is None or comment_id is None:
        abort(400)
    support.process_vote(comment_id, g.user.name, value)
    return "success"
Parâmetros:
  • comment_id – o comentário em votação

  • username – o nome único de usuário do usuário que votou

  • value – 1 para subir voto, -1 para diminuir voto, 0 para não votado.

WebSupport.get_search_results(q)[código fonte]

Executar busca para query q e criar um conjunto de resultados de pesquisa. O renderizador de resultados de busca como html e retorna o contexto como dicionário criado por get_document():

document = support.get_search_results(q)
Parâmetros:

q – consulta de busca