NPL Package in development
Project description
CID-DOCS
Bienvenidos al sitio de documentación del Centro de investigación Digitial del Instituto Tecnologico de Buenos Aires
Hemos armado un tutorial que les enseñara paso a paso como auto-documentar un proyecto con Sphinx y publicar la documentación de su proyecto en Read the Docs.
Una vez alcanzado este objetivo ahondaremos en como publicar nuestro paquete en PYPI para poder instalarlo mediante pip.
Preparando los Docstrings
Se llaman docstring a un formato especial de comentario que se utiliza para dar estructura a la documentación. Con estos podemos especificar detalladamente el funcionamiento de las clases y metodos implementados.
Existen diversos formatos de doctrings compatibles con Sphinx.
- Sphynx Style
- Google Style
- Numpy Style
Pueden aprender más acerca de estos y como utilizarlos aquÃ.
En nuestro caso hemos decidido utilizar Numpy Style por su simplicidad y practicidad para documentar.
class Hotel:
"""
El hotel tiene varias habitaciones
Parameters
--------
nombre : str
Nombre del hotel
cuartos : int
Cantidad de cuartos en el hotel
"""
def __init__(self, nombre, cuartos):
self.cuartos = cuartos
self.nombre = nombre
def make_meal(self, name, size, temperature)
"""
Parameters
--------
name : str
Type of food to prepare
size : float
How many kilos to prepare
temperature : float
How hot it should be
Returns
--------
meal : object
Your desired meal
Raises
------
ValueError
if 'name' is not present is not a meal.
Examples
--------
>>> hotel = Hotel("PythonHotel", 400)
>>> hotel.make_meal("Fried Chicken", 4)
See Also
--------
Hotel.make_dessert : for instruction on how to make a dessert.
"""
pass
def make_dessert(self, name, size)
"""
...
"""
pass
Para más ejemplos de documentación les recomendamos mirar el codigo de fuente de SimilarityLab o Numpy
Empaquetando
Nuestro proyecto tiene que poder ser identificado como un paquete distribuible de Python. Para ello necesitamos dos archivos escenciales, __init__.py
y setup.py
. Ambos deben alojarse en el mismo directorio que nuestro modulo.
El archivo __init__.py
solamente deber exisitir y puede estar vacio. No hay más requerimientos que esos.
Para que Sphinx pueda rastrear la versión en la que actualmente estamos trabajando, como asà conocer las dependencias de nuestro proyecto, es necesario generar un archivo setup.py
.
El mismo debe encontrarse en el mismo directorio que nuestra clase.
import setuptools
with open("README.md", "r") as fh:
long_description = fh.read()
setuptools.setup(
name="ProjectName",
version="0.0.1",
author="Example Author",
author_email="author@example.com",
description="A small example package",
long_description=long_description,
long_description_content_type="text/markdown",
keywords='Cats dogs words',
url="https://github.com/pypa/sampleproject",
packages=setuptools.find_packages(),
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
install_requires=[
'numpy',
'scipy',
'SimiLab',
],
python_requires='>=3.6',
)
Sphinx
Primeros pasos
Para poder generar nuestra documentación vamos a requerir instalar Sphinx.
pip install sphinx
y para generar nuestro archivo de requerimientos necesitaremos
pip install pipreqs
Una vez instalados corremos desde el directorio raiz de nuestro proyecto
>\MyProject sphinxquickstart docs -ext-autodoc
Recomendamos seguir las opciones por defecto que nos ofrece la CLI de Sphinx.
Una vez terminado deberiamos tener la siguiente estructura:
-MyProject
-MyPackage
-package.py
-__init__.py
-setup.py
-docs
-docs
-conf.py
-index.rst
-make.bat
-Makefile
:construction: index.rst :construction:
Asà como en HTML se trabaja con un archivo principal llamado index.html. Cuando trabajamos con sphinx vamos a tener un punto de entrada llamado index.rst. Aquà ensamblaremos la estructura de nuestra documentación. En este caso utilizamos reStructuredText como lenguaje de markup.
Welcome to SimilarityLab's documentation!
=========================================
.. toctree::
:maxdepth: 2
:caption: Contents:
pages/getting-started
.. automodule:: SimiLab
:members:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
La indentación es vital para no incurrir en errores al momento de compilar.
Por ejemplo la directiva automodule le dice a Sphinx que tome todos los docstrings contenidos en SimiLab
conf.py
El archivo conf.py es generado de forma automatica luego de llamar a sphinxquickstart. Para permitir que Sphinx encuentre nuestro paquete es necesario indicarle donde se encuentra. Sugerimos utilizar de ejemplo el archivo conf.py que se encuentra aquÃ.
Recordar configurar
- Extensiones de Sphinx
- Path
- Tema (sugerimos 'default')
Archivos .readthedocs.yml y requirements.txt
Ciertamene la mayorÃa de los proyectos requieren ciertas dependecias externas. Sin embargo, aunque sean paquetes de terceros, hay que especificar cuales son.
- En el directorio raiz crear un archivo .readthedocs.yml
- Copiar el archivo de ejemplo
>MyProject/MyPackage pipreqs > requirements.txt
Se recomienda mover el mismo a la carpeta docs
:construction: make html, rdft :construction:
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for SimilarityLab-0.0.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0671dd33968e2beb141971fcae628a3a585ea1073de7ccb4f9da726e5eff019c |
|
MD5 | 456491e6c67a0a65c527cf4f3086b27f |
|
BLAKE2b-256 | 3c70ab1393bc4ce45891777f9fd0b46d27b23ad62cad2d7753e2cf5f7ba98fe9 |