Classe WebSupport

class sphinxcontrib.websupport.WebSupport

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

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

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

Ler arquivos reStructured text do diretório fonte srcdir. Então será construído dados e índices, colocando isso no builddir. Também salva dados no banco de dados.

WebSupport.get_document(docname, username='', moderator=False)

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)

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)

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)

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)

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