.readthedocs.yaml

 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

CHANGELOG.md

+## 0.2.0 (2024-03-26)
+
+### Feat
+
+- use theme furo and Markdown
+
 ## 0.1.0 (2022-11-03)
 
 ### Feat

Makefile

@@ -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).

Pipfile

@@ -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"

README.md

 # 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.

cz.yaml

+---
 commitizen:
   name: cz_conventional_commits
   tag_format: $version
-  version: 0.1.0
+  version: 0.2.0

requirements.txt

-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'

scripts/generate-requeriments.sh

-#!/usr/bin/sh
-pipenv lock -r > requirements.txt

source/_templates/page.html

+{% set next = None %}
+{% set prev = None %}
+{% extends "!page.html" %}

source/conf.py

@@ -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"]

source/index.md

+# Documentação de exemplo
+
+```{toctree}
+:maxdepth: 2
+:caption: "Conteúdo"
+:glob:
+
+pages/*
+```

source/index.rst

-.. 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`

source/pages/example.md

+# 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
+:::

source/pages/example2.md

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