Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • c3sl/rdt-docs
  • c3sl/c3docs/suporte
  • c3sl/c3docs/devops
  • cms/cms-docs
  • c3sl/ademir-docs
5 results
Show changes
Commits on Source (2)
version: 2
build:
os: ubuntu-20.04
os: ubuntu-22.04
tools:
python: "3.10"
python: "3.11"
python:
install:
- requirements: ./requirements.txt
......@@ -11,4 +11,4 @@ sphinx:
configuration: source/conf.py
formats:
- pdf
- epub
- hmlzip
## 0.2.0 (2024-03-26)
### Feat
- use theme furo and Markdown
## 0.1.0 (2022-11-03)
### Feat
......
This diff is collapsed.
......@@ -12,7 +12,10 @@ BUILDDIR = build
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
dev:
@sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile dev
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
......
......@@ -8,8 +8,14 @@ sphinx = "*"
sphinx-rtd-theme = "*"
commitizen = "*"
pre-commit = "*"
furo = "*"
sphinx-autobuild = "*"
sphinx-inline-tabs = "*"
sphinx-copybutton = "*"
sphinx-tippy = "*"
myst-parser = "*"
[dev-packages]
[requires]
python_version = "3.10"
python_version = "3.11"
This diff is collapsed.
# Template Read the docs
Este repositório server de template para documentação do readthedocs do C3SL
Este repositório server de template para documentação do ReadTheDocs do C3SL
[docs](docs.c3sl.ufpr.br).
[[_TOC_]]
# Como começar
O primeiro passo é realizar o folk do template e depois clonar o folk.
Após clonar, edite a documentação localizada em `sources` e quando terminar faça push para o gitlab
e link no [docs](docs.c3sl.ufpr.br).
O primeiro passo é realizar o fork do template.
Após clonar, edite a documentação localizada em `sources` e quando terminar
faça push para o gitlab e crie a documentação no [docs](docs.c3sl.ufpr.br).
# Organização do repositório
O repositório é dedicado a documentação e esta orgazanizado da seguinte maneira:
* `build/` Diretório onde os arquivos compilados vão.
* `cz.yaml` Arquivo de configuração do commitizen
* `.git` Diretório de configuração do git
* `.gitignore`Arquivo com padrões de nomes que o git deve ignorar ao realizar `git add` ou `git
stage`
* `Makefile` Makefile para fazer o build da documentação, resultado vai para o diretório `build`
* `Pipfile` Arquivo do pipenv para criar ambiente do python para fazer build
* `Pipfile.lock` Arquivo do pipenv para criar ambiente do python para fazer build
* `.pre-commit-config.yaml` Arquivo de configuração do pre-commit
* `README.md` arquivo de readme do repositório.
* `.readthedocs.yaml` Arquivo de configuração do readthedocs
* `requirements.txt` Arquivos com listas de modulos python para fazer build da documentação, deve
ser igual ao `Pipfile`
* `LICENSE` arquivo de licença
* `.gitlab-ci.yml` Arquivo do Gitlab CI
* `scripts/` Diretório com scripts variados.
* `generate-requeriments.sh` Script que gera o arquivo `requirements.txt` a partir do `Pipfile`.
* `source/` Diretório da documentação.
* `conf.py` Arquivo de configuração do sphinx
* `index.rst` Primeira página da documentação
* `pages/` Diretório com as páginas da documentação
* `quickstart-rst.rst` Página com dicas de rst com sphinx
* `quickstart-conf.rst` Página com dicas de configuração do `conf.py`
* `quickstart-rdt.rst` Página de como incluir um repositório em [docs](docs.c3sl.ufpr.br)
* `_static/` Diretório para armazenar arquivos estáticos, como imagens, gifs e etc.
* `_templates/` Diretório para armazenar estilização das páginas, css, html e etc.
A gestão dos pacotes é feita através do Pipenv. Para instalar use `pipenv install`,
e para entrar no ambiente virtual, `pipenv shell`. Para gerar a documentação
rode `pipenv run make html`. Para desenvolvimento local recomenda-se utilizar
o servidor automático com `pipenv run make dev`.
Para usar o pre-commit hook que reformata os arquivos documentação ao fazer
commit, depois de clonar o repositório rode `pipenv run pre-commit install`.
O repositório está organizado da seguinte maneira:
* `.pre-commit-config.yaml`: Configuração do pre-commit.
* `cz.yaml`: Configuração do commitizen.
* `Makefile`: Configuração do Make para a documentação.
* `Pipfile`: Configuração do ambiente Python usando Pipenv.
* `Pipfile.lock`: Versão dos módulos Python atual. Este arquivo deve ser incluído no git.
* `README.md`: Arquivo que você está lendo.
* `.readthedocs.yaml`: Configuração do ReadTheDocs.
* `requirements.txt`: Listas de módulos utilizada pelo ReadTheDocs que deve ser igual ao `Pipfile`, podendo ser regerada com `pipenv requirements >requirements.txt`.
* `LICENSE`: Licença do repositório, padrão é a GPLv3.
* `build/`: Diretório da documentação compilada.
* `source/`: Diretório da documentação.
* `conf.py`: Configuração do Sphinx.
* `index.rst`: Página inicial da documentação.
* `pages/`: Diretório com as páginas da documentação.
* `_static/`: Diretório para armazenar arquivos estáticos como imagens, gifs e etc.
* `_templates/`: Diretório para alterar o estilo das páginas.
* `_ext/`: Diretório para extensões customizadas do Sphinx.
---
commitizen:
name: cz_conventional_commits
tag_format: $version
version: 0.1.0
version: 0.2.0
sphinx
sphinx-rtd-theme
commitizen
pre-commit
-i https://pypi.org/simple
alabaster==0.7.16 ; python_version >= '3.9'
argcomplete==3.2.3 ; python_version >= '3.8'
babel==2.14.0 ; python_version >= '3.7'
beautifulsoup4==4.12.3 ; python_full_version >= '3.6.0'
certifi==2024.2.2 ; python_version >= '3.6'
cfgv==3.4.0 ; python_version >= '3.8'
charset-normalizer==3.3.2 ; python_full_version >= '3.7.0'
colorama==0.4.6 ; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6'
commitizen==3.20.0
decli==0.6.1 ; python_version >= '3.7'
distlib==0.3.8
docutils==0.20.1 ; python_version >= '3.7'
filelock==3.13.3 ; python_version >= '3.8'
furo==2024.1.29
identify==2.5.35 ; python_version >= '3.8'
idna==3.6 ; python_version >= '3.5'
imagesize==1.4.1 ; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
importlib-metadata==7.1.0 ; python_version >= '3.8'
jinja2==3.1.3 ; python_version >= '3.7'
livereload==2.6.3
markdown-it-py==3.0.0 ; python_version >= '3.8'
markupsafe==2.1.5 ; python_version >= '3.7'
mdit-py-plugins==0.4.0 ; python_version >= '3.8'
mdurl==0.1.2 ; python_version >= '3.7'
myst-parser==2.0.0
nodeenv==1.8.0 ; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6'
packaging==24.0 ; python_version >= '3.7'
platformdirs==4.2.0 ; python_version >= '3.8'
pre-commit==3.7.0
prompt-toolkit==3.0.36 ; python_full_version >= '3.6.2'
pygments==2.17.2 ; python_version >= '3.7'
pyyaml==6.0.1 ; python_version >= '3.6'
questionary==2.0.1 ; python_version >= '3.8'
requests==2.31.0 ; python_version >= '3.7'
setuptools==69.2.0 ; python_version >= '3.8'
six==1.16.0 ; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
snowballstemmer==2.2.0
soupsieve==2.5 ; python_version >= '3.8'
sphinx==7.2.6
sphinx-autobuild==2024.2.4
sphinx-basic-ng==1.0.0b2 ; python_version >= '3.7'
sphinx-copybutton==0.5.2
sphinx-inline-tabs==2023.4.21
sphinx-rtd-theme==2.0.0
sphinx-tippy==0.4.1
sphinxcontrib-applehelp==1.0.8 ; python_version >= '3.9'
sphinxcontrib-devhelp==1.0.6 ; python_version >= '3.9'
sphinxcontrib-htmlhelp==2.0.5 ; python_version >= '3.9'
sphinxcontrib-jquery==4.1 ; python_version >= '2.7'
sphinxcontrib-jsmath==1.0.1 ; python_version >= '3.5'
sphinxcontrib-qthelp==1.0.7 ; python_version >= '3.9'
sphinxcontrib-serializinghtml==1.1.10 ; python_version >= '3.9'
termcolor==2.4.0 ; python_version >= '3.8'
tomlkit==0.12.4 ; python_version >= '3.7'
tornado==6.4 ; python_version > '2.7'
urllib3==2.2.1 ; python_version >= '3.8'
virtualenv==20.25.1 ; python_version >= '3.7'
wcwidth==0.2.13
zipp==3.18.1 ; python_version >= '3.8'
#!/usr/bin/sh
pipenv lock -r > requirements.txt
{% set next = None %}
{% set prev = None %}
{% extends "!page.html" %}
......@@ -3,25 +3,52 @@
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import os
import sys
sys.path.append(os.path.abspath("./_ext"))
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = "Template-RDT"
copyright = "2022, Odair M."
author = "Odair M."
project = "Exemplo"
copyright = "2024 Odair M., Fernando K."
author = "Odair M., Fernando K."
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = []
language = "pt"
templates_path = ["_templates"]
exclude_patterns = []
language = "pt"
extensions = [
"sphinx.ext.todo",
"sphinx_inline_tabs",
"sphinx_copybutton",
"sphinx_tippy",
"myst_parser",
]
myst_enable_extensions = [
"colon_fence",
"deflist",
"fieldlist",
]
myst_heading_anchors = 2
copybutton_prompt_text = r">>> |\$ |.+:.+# |.+@.+> |<.+>"
copybutton_prompt_is_regexp = True
copybutton_line_continuation_character = "\\"
copybutton_here_doc_delimiter = "EOF"
copybutton_copy_empty_lines = False
todo_include_todos = True
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "alabaster"
html_theme = "furo"
html_static_path = ["_static"]
# Documentação de exemplo
```{toctree}
:maxdepth: 2
:caption: "Conteúdo"
:glob:
pages/*
```
.. Template-RDT documentation master file, created by
sphinx-quickstart on Wed Nov 2 22:52:13 2022.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Template-RDT's documentation!
========================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
# Página de exemplo
:::{todo}
Terminar esta página
:::
:::{list-table}
* - **Tamanho desta página**
- Alguns kilobytes
* - **Data de criação**
- 2024-03-26
:::
Essa é uma página de exemplo.
```console
$ ping -c 1 docs.c3sl.ufpr.br
PING docs.c3sl.ufpr.br(docs.c3sl.ufpr.br (2801:82:80ff:8002:216:ccff:feaa:72)) 56 bytes de dados
64 bytes de docs.c3sl.ufpr.br (2801:82:80ff:8002:216:ccff:feaa:72): icmp_seq=1 ttl=63 tempo=0.464 ms
--- docs.c3sl.ufpr.br estatísticas de ping ---
1 pacotes transmitidos, 1 recebidos, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.464/0.464/0.464/0.000 ms
```
|Podemos construir|Algumas tabelas |
|-----------------|-------------------------|
|Faz parte do que |o Markdown consegue fazer|
## Configuração
:::{note}
É possível fazer bem mais
:::
# Página de exemplo 2
## Se quisermos linkar para outra página, é só referenciar
* [Pode ser relativo.](example)
* [E pode ser absoluto.](/pages/example)
## Que tal linkar para um conteúdo dentro de outra página?
:::{warning}
Acho que talvez seja uma ideia interessante.
:::
[Veja bem que precisa da extensão .md neste caso.](/pages/example.md#configuracao)