Migrate docs to sphinx

mstuttgart · Nov 23, 2024 · ff07075 · ff07075
1 parent 665bbff
commit ff07075
Show file tree

Hide file tree

Showing 31 changed files with 744 additions and 614 deletions.
diff --git a/.github/ISSUE_TEMPLATE/custom.md b/.github/ISSUE_TEMPLATE/custom.md
@@ -6,5 +6,3 @@ labels: Question
 assignees: ''
 
 ---
-
-
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -24,7 +24,7 @@ repos:
       - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.7.4
+    rev: v0.8.0
     hooks:
       - id: ruff
 

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -19,5 +19,5 @@ python:
       extra_requirements:
         - docs
 
-mkdocs:
-  configuration: mkdocs.yml
+sphinx:
+  configuration: docs/conf.py
diff --git a/CHANGELOG.md → CHANGELOG b/CHANGELOG.md → CHANGELOG
@@ -1,42 +1,51 @@
-# Changelog
+Changelog
+=========
 
-## 6.5.0 (2024-08-18)
+6.5.0 (2024-08-18)
+------------------
 
 - Remove API Correios from website.
 
-## 6.4.1 (2024-08-18)
+6.4.1 (2024-08-18)
+------------------
 
 - Fix beautifulsoup4 version
 
-## 6.4.0 (2024-08-14)
+6.4.0 (2024-08-14)
+------------------
 
 - Add API Correios (via Correios site) support
 - Add OpenCEP support
 
-## 6.3.1 (2024-05-05)
+6.3.1 (2024-05-05)
+------------------
 
 Update copyright and python version
 
-## 6.3.0 (2024-05-05)
+6.3.0 (2024-05-05)
+------------------
 
 - Change poetry `pyproject.toml` and use default `pyproject.toml` from Python docs
 - Improve nox tests and dependencies enviromnents
 - Add support to Python 3.12
 
-## 6.2.0 (2023-10-01)
+6.2.0 (2023-10-01)
+------------------
 
 - Add timeout settings
 - Add proxy settings. From: https://github.com/mstuttgart/brazilcep/issues/40
 - Add real tests to APICEP and ViaCEP
 - Update docs and README
 - Deprecated 'Correios' webservice support
 
-## 6.1.0 (2023-10-01)
+6.1.0 (2023-10-01)
+------------------
 
 - Add timeout parameters in requests
 - Update README typing errors
 
-## 6.0.0 (2023-04-30)
+6.0.0 (2023-04-30)
+------------------
 
 - Rename lib to BrazilCEP
 - Create new pip package
@@ -52,13 +61,15 @@ Update copyright and python version
 - Create docs site (translate to English)
 - Update contribute doc to use poetry
 
-## 5.1.0 (2022-10-12)
+5.1.0 (2022-10-12)
+------------------
 
 * Corrige: AttributeError: 'NoneType' object has no attribute 'split' ao consultar cep 99999-999
 * Adiciona nova exception 'BlockedByFlood' para excesso de consultas
 * Melhoras testes adicionando mock as consultas de ViaCEP e ApiCEP
 
-## 5.0.0 (2021-01-07)
+5.0.0 (2021-01-07)
+------------------
 
 * Adiciona suporte para Python 3.8
 * Adiciona integração com consulta de CEP nos webservices dos Correios
@@ -71,26 +82,31 @@ Update copyright and python version
 * Uso de TOX para testes em diferentes versões do Python
 * Adiciona novos testes e aumenta taxa do coverage
 
-## 4.0.4 (2020-08-18)
+4.0.4 (2020-08-18)
+------------------
 
 * Corrige "AttributeError: 'ConnectionError' object has no attribute 'message'"
 
-## 4.0.3 (2020-06-08)
+4.0.3 (2020-06-08)
+------------------
 
 * Corrige 'get_cep_from_address' error key - thanks Hendrix Costa https://github.com/hendrixcosta
 * Corrige docs
 
-## 4.0.2 (2020-05-31)
+4.0.2 (2020-05-31)
+------------------
 
 * Corrige exemplo de uso do 'get_cep_from_address'
 * Corrige "(client): KeyError exception when address not found" - thanks Patrick Ferraz https://github.com/patricksferraz
 * Adiciona captura de erro com status_code=200 - thanks Bruno Mello https://github.com/bgmello
 
-## 4.0.1 (2020-02-22)
+4.0.1 (2020-02-22)
+------------------
 
 * Corrige travis.yml deploy
 
-## 4.0.0 (2020-02-22)
+4.0.0 (2020-02-22)
+------------------
 
 * Adiciona suporte a API do ViaCEP (https://viacep.com.br/)
 * Adiciona consulta de faixa de CEPs
@@ -101,56 +117,65 @@ Update copyright and python version
 
 Milestone: https://github.com/mstuttgart/pycep-correios/milestone/4
 
-## 3.2.0 (2019-08-18)
+3.2.0 (2019-08-18)
+------------------
 
 * Remove suporte para Python 3.4: https://www.python.org/downloads/release/python-3410/
 * Adiciona suporte para retorno com atributos ausentes
 * Adiciona mock aos testes
 
-## 3.1.0 (2018-11-11)
+3.1.0 (2018-11-11)
+------------------
 
 * Correção no tipo do retorno do metodo consultar_cep (por questões de compatibilidade, agora retorna um dict)
 * Correção da documentação, pois as tags 'id' e 'complemento' não estão mais sendo retornadas pelo Correios.
 * Atualização do README.md para uso de markdown no pypi e documentação.
 
-## 3.0.0 (2018-10-21)
+3.0.0 (2018-10-21)
+------------------
 
 * Alteração da API de consulta para [python-zeep](https://pypi.org/project/zeep/)
 * Antigas `exceptions` agora estão `deprecated`. Usar apenas `ExcecaoPyCEPCorreios`
 * Atualização da documentação
 * Remoção do suporte para Python 2.7
 
-## 2.3.1 (2018-05-03)
+2.3.1 (2018-05-03)
+------------------
 
 * Corrige README.rst
 * Adiciona comando para validação dpo setup.py no Makefile
 * Corrige link do repositorio e donwload
 
-## 2.3.0 (2018-05-03)
+2.3.0 (2018-05-03)
+------------------
 
 * Adiciona logging para consulta de CEP
 * Adiciona documentação em inglês
 * Versão requirida das libs *requests* e da *Jinja2* limitadas por baixo, para fins de compatibilidade
 * Remove suporte para Python 3.3
 
-## 2.2.0 (2017-07-16)
+2.2.0 (2017-07-16)
+------------------
 
 * Melhorias no metodo de formatar_cep, que agora passou a utilizar expressão regular para verificar se o CEP é formado por caracteres.
 * A função *formatar_cep* agora passa a lançar a exceção *Value Error* quando o CEP não possui estrutura válida https://github.com/mstuttgart/pycep-correios/pull/22
 * Adicionado novas exceções ExcecaoPyCEPCorreios, Timeout, MultiploRedirecionamento, FalhaNaConexao. Consultar documentacao para exemplos de utilização delas. close https://github.com/mstuttgart/pycep-correios/issues/25
 * Adicionado ambientes de *Homologação* e *Producao*. Facilitando realizar consultas utilizadas para testes. close https://github.com/mstuttgart/pycep-correios/issues/24
 * Melhorias na organização da API.
 
-## 2.1.1 (2017-06-30)
+2.1.1 (2017-06-30)
+------------------
 
 * Correção de erros de unicode com python2.7
 
-## 2.1.0 (2017-06-29)
+2.1.0 (2017-06-29)
+------------------
 
 * Adicionado suporte para Python 2.7+
 * Ajustes e correções na documentação
 
-## 2.0.0 (2017-06-20)
+2.0.0 (2017-06-20)
+------------------
 
 * Atualização do código da PyCEPCorreios, deixando-a mais facil de ser utilizada
 * Remoção das exceções antigas, deixando apenas a Exceção padrão da lib
@@ -160,40 +185,47 @@ Milestone: https://github.com/mstuttgart/pycep-correios/milestone/4
 * Adicionado testes com TOX
 * Adicionado método de validação de CEP e formatação de CEP
 
-## 1.1.7 (2017-05-09)
+1.1.7 (2017-05-09)
+------------------
 
 * Corrigido erro `jinja2.exceptions.TemplateNotFound: consultacep.xml`
 * Erro durante instalação da PyCEPCorreios via pip
 * Atualizado código de exemplo no README.rst
 * Atualizado exemplos na documentação
 
-## 1.1.6 (2017-05-08)
+1.1.6 (2017-05-08)
+------------------
 
-* Correção de bug durante instalação. #15
+* Correção de bug durante instalação. 15
 * Correção de template xml ausente no pacote do modulo
 * Melhorias gerais no código e correções de bugs
 
-## 1.1.1 (2017-02-08)
+1.1.1 (2017-02-08)
+------------------
 
 * Melhorias gerais no código
 * XML schema utilizando Jinja2
 
-## 1.0.1 (2016-08-03)
+1.0.1 (2016-08-03)
+------------------
 
 * Simplificação da classes Exceptions
 * Organização do código de teste
 * Utilização do mock para test
 
-## 1.0.0 (2016-07-31)
+1.0.0 (2016-07-31)
+------------------
 
 * API migrada para Python 3. Python 2.7 não será mais suportado
 * Substituição da lib *suds* pela lib *requests* para realizar as requisições
 
-## 0.0.2 (2016-05-09)
+0.0.2 (2016-05-09)
+------------------
 
 * `setup.py` com número de versão atualizado e dependência corrigidas.
 
-## 0.0.1 (2016-05-05)
+0.0.1 (2016-05-05)
+------------------
 
 * Versão inicial.
 * Permite busca no webservice dos correios dos dados de um CEP fornecido.
diff --git a/Makefile b/Makefile
@@ -15,7 +15,7 @@ help:
 .PHONY : check
 check:
 	make pre-commit
-	# make docs
+	make docs
 	make test
 	make build
 
@@ -40,19 +40,21 @@ build :
 
 .PHONY : coverage
 coverage:
-	pytest --cov=. --cov-config=pyproject.toml --cov-report term-missing --no-cov-on-fail
+	pytest --cov=brazilcep --cov-config=pyproject.toml --cov-report term-missing --no-cov-on-fail --cov-report=html
 
 .PHONY : lint
 lint:
-	isort --check .
-	black --check brazilcep tests --exclude .tox
-	ruff check .
+	isort --check brazilcep tests
+	black --check brazilcep tests
+	ruff check brazilcep tests
 	CUDA_VISIBLE_DEVICES='' pytest -v --color=yes --doctest-modules tests/ brazilcep/
 
 .PHONY : docs
 docs:
-	sphinx-build -E -T -W -b html -D language=en -j auto -q docs/source docs/build
+	rm -rf docs/build/
+	sphinx-autobuild -b html --watch brazilcep/ docs/source/ docs/build/
 
+.PHONY : pre-commit
 pre-commit:
 	pre-commit run --all-files
 
@@ -64,6 +66,7 @@ setup:
 	pip install -e ".[build]"
 	pre-commit install --hook-type pre-commit
 	pre-commit install --hook-type pre-push
+	pre-commit autoupdate
 
 .PHONY : test
 test:

diff --git a/README.md b/README.md
@@ -13,7 +13,11 @@
   </a>
 
  <a href="https://codecov.io/gh/mstuttgart/brazilcep" >
- <img alt="Codecov" src="https://img.shields.io/codecov/c/github/mstuttgart/brazilcep?color=fcd800">
+  <img alt="Codecov" src="https://img.shields.io/codecov/c/github/mstuttgart/brazilcep?color=fcd800">
+ </a>
+
+<a href="https://brazilcep.readthedocs.io/" >
+  <img alt="readthedocs" src="https://img.shields.io/readthedocs/brazilcep?color=fcd800">
  </a>
 
   <a href="https://pypi.org/project/brazilcep">
@@ -41,7 +45,7 @@
 
 ## About
 
-**BrazilCEP** is a minimalist and easy-to-use python library designed to query CEP (Postal Address Code) data.
+**BrazilCEP** is a minimalist and easy-to-use Python library designed to query CEP (Postal Address Code) data.
 
 Its objective is to provide a common query interface to all these search services, facilitating the integration of Python applications with these services.
 
@@ -51,7 +55,7 @@ Currently supports several CEP API's:
 - [ApiCEP (WideNet)](https://apicep.com)
 - [OpenCEP](https://opencep.com/)
 
-> [!NOTE] > **BrazilCEP** is the new name of former **PyCEPCorreio** python library.
+> [!NOTE] > **BrazilCEP** is the new name of former **PyCEPCorreio** Python library.
 > If you want to migrate the old code to the new version, please see the [migrate](https://brazilcep.readthedocs.io/en/latest/migrate/) section in docs.
 
 > [!TIP] > **CEP** or **Código de Endereçamento Postal** (_Postal Address Code_), as it is also known, is a system of numeric codes, created, maintained and organized by _Correios do Brazil_ for

diff --git a/brazilcep/__init__.py b/brazilcep/__init__.py
@@ -8,13 +8,15 @@
 Its objective is to provide a common query interface to all these search services,
 facilitating the integration of Python applications with these services.
 
-:copyright: (c) 2023 by Michell Stuttgart.
+:copyright: (c) 2024 by Michell Stuttgart.
 :license: MIT, see LICENSE for more details.
 """
 
+from .__version__ import __version__
 from .client import WebService, get_address_from_cep
 
 __all__ = [
     "get_address_from_cep",
     "WebService",
+    "__version__",
 ]
diff --git a/brazilcep/__version__.py b/brazilcep/__version__.py
@@ -0,0 +1 @@
+__version__ = "6.5.0"
diff --git a/brazilcep/client.py b/brazilcep/client.py
@@ -53,7 +53,7 @@ def get_address_from_cep(cep, webservice=WebService.APICEP, timeout=None, proxie
         RequestError: When connection error occurs in CEP query
         Timeout: When occurs timeout of webservice response
         HTTPError: Invalid HTTP format query
-        CEPNotFund: CEP not exist in API
+        CEPNotFound: CEP not exist in API
         Exception: When any error occurs in the CEP query
 
     returns: