Learning how to post python packages in PyPi, github, ReadtheDocs
Project description
PyPi, GitHub, ReadTheDocs competencies
After spending one week trying to get ReadTheDocs documentation for melib
without success, I decided to start from small and start learbibg the ropes the first. Hence, this project.
In this project, I will start from a simple package with no dependencies. Once I figure out how to pypi
and readthedocs
it, I will gradually make it more and more complex until I reach melib
complexity. This file will document the progress.
One Module, one file : hgdemo.circle.py
I checked a few 'single module' entries on GitHub
to find an example to follow.
I picked requests
as an example because
- It is popular and reputable package
- It has
ReadTheDocs
documentation - The repository has only one module (like my
melib
)
Structure for the GitHub
repository requests
:
- Owner name: psf https://github.com/psf
- Repository name: requests https://github.com/psf/requests
- Repository structure
.github
I am not sure what this is for. My guess is you need it when you have collaboration with multiple coders.docs
Documentation folder (it looks like the documentation was created using sphinx)ext
This includes image files presumably all from other sourcesrequests
This is the folder where you have the module files__init.py__.py
__version__.py
_internal.utils.py
adapters.py
- (and 14 other files with
py
extsnsions)
So let us create a structure for hgdemo
using the repository requests
as en example.
$ mkdir hgdemo
This folder will be the hgdemo
module. All python files will be in this folder.
$ cd hgdemo
Create circle.py
module with two functions in the module folder (hgdemo
). These are area(r)
and peri(r)
. Both functions and the module file itself have docstrings.
Then create an empty file called __init__.py
in the same folder as circle.py
(the inner hgdemo
folder)
Finally, make a docs
folder in the root folder. We can now start following the sphinx
process to create local dumentation.
Local Documentation using sphinx
This is the folder structure at this point:
hgdemo
docs
\ (empty folder)hgdemo
\__init__.py
(empty file)circle.py
(with two functions:area
andperi
)
README.md
(this file)
In VS Code, go to the docs
folder and enter
$ sphinx-quickstart
Enter the questions as follows:
Separate source and build directories (y/n)[n]: Pick the default ([n])
Project name: hgdemo
Author name(s): H Gurgenci
Project release []: June 2021
Project language [en]: __
sphinx
then ends with the note thatr the following files were created:
Creating file H:\My Documents\git\hgdemo\docs\conf.py.
Creating file H:\My Documents\git\hgdemo\docs\index.rst.
Creating file H:\My Documents\git\hgdemo\docs\Makefile.
Creating file H:\My Documents\git\hgdemo\docs\make.bat.
This is the folder structure at this point:
hgdemo
docs
\_build
\_static
\_templates
\conf.py
index.rst
make.bat
Makefile
hgdemo
\__init__.py
(empty file)circle.py
(with two functions:area
andperi
)
README.md
(this file)
Edit conf.py
Path
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
Extensions (I copied this from the conf file in the requests repository):
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx.ext.viewcode",
]
Edit index.rst
This is the index
file after I edit it:
.. hgdemo documentation master file, created by sphinx-quickstart on Thu Jun 3 15:18:04 2021.
hgdemo documents python package creation process
================================================
A simple header
===============
The module has two files: circle.py and square.py.
I did go through the process with one file (circle) first and then repeated the process.
A log of my actions can be seen in the file README.md.
print(hgdemo.circle(2)
>> 12.56
Guide
^^^^^
.. toctree::
:maxdepth: 2
api.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Create api.rst
I create an pi.rst
file with the following contents:
hgdemo API reference
========================
.. module:: hgdemo
This is a short API file demonstrating the bare essentials.
.. automodule:: hgdemo.circle
:members:
Run ./make html
The docs/_build/html/api.html and docs/_build/html/index.html files are generated by sphinx. All good.
Remote Documentation
git init
onH:\My Documents\git\hgdemo
- Create
.gitignore
with my standard ignore lines:- *.pyc
- tmp
- pop
- .ipynb_checkpoints
git add -A
git commit -am
'the first commit'- log in to github
- Create
hgdemo
as an empty repository git remote add origin
https://github.com/Gurgenci/hgdemo.gitgit branch -M main
git push origin main
- Log in to
ReadtheDocs.org
- Import a repository (hgdemo)
The documentation is created: http://hgdemo.readthedocs.io/
Create a second module, square
.
The second module has two functions: area
, side
and it imports numpy
.
Add it to the local git
- Add the following two lines to the end of
api.rst
:
.. automodule:: hgdemo.square
:members:
- ./make html
Add it to the github:
git add -A
git commit -am
'the secod module: square'git push origin main
- Refresh the
Overview
inReadtheDocs
projecthgdemo
- Build Version
- (even when I refresh, ReadtheDocs sometimes fails to reead the new the project and the Billd fails. I then reset and wipe and latest and start again. This usually works.)
ReadTheDocs
did not process square.py
. The build notes says:
WARNING: autodoc: failed to import module 'square' from module 'hgdemo'; the following exception was raised:
No module named 'numpy'
Unfortunately, the requests
does not seem to be accessing numpy
.
requirements.txt
I add the following file to docs
folder:
numpy>=1.0
This made it possible to import square
. But there were problems in the documentation.
Rename area
in square
to sqarea
and repeat ./make html
.
This time it worked. I also note that I had to refresh the readthedocs View Docs
pages to see the new changes. Maybe this was the problem in the previous build.
Register the hgdemo
in PyPi
- Create two files in the root folder:
setup.cfg:
[metadata]
name = hgdemo
version = 0.0.1
author = Hal Gurgenci
author_email = h.gurgenci@uq.edu.au
description = For analysing strength of machine elements
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/Gurgenci/hgdemo
classifiers =
Programming Language :: Python :: 3
License :: OSI Approved :: MIT License
Operating System :: OS Independent
[options]
packages = find:
python_requires = >=3.0
include_package_data = True
pyproject.toml :
[build-system]
requires = [
"setuptools>=42",
"wheel"
]
build-backend = "setuptools.build_meta"
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.