Package: melib
pip install melibDocumentation :https://melib.readthedocs.io/en/latest/There are three files in this package:library.py -- a collection of small functions that can be used to execute small tasks associated with the design of mechanical components such as belts and chains, gears, rotating shafts, keys, bearings, welded joints, welded structures, fasteners, etc.  The module is designed to be used in teaching machine element design to second-year mechanical students. To motivate learning of procedures and relevant standards, there are no pushbutton complete designs. Unless otherwise specified, the formula and data reference is ‘Machine Elements in Mechanical Design’ by Mott.  There is a collection of Excel data files that are accessed by the library. These files are in the data folder. This is not a comprehensive machine design library but sufficient for preparing assignments, examples and exam questions.xt.py -- Functions that can be called upon to generate jupyter notebooks for documenting the mechanical design tasks. It also has functions to create pdf documentsexcel.py -- functions to read and write Microsoft Excel files. It uses the python package openpyxl.This was the first project I registered inPyPiuploaded toGitHubwith documentation atuomatically generated usingReadTheDocs.
I document every step to help others and future self in similar endeavours.Construct local repositoryI create a local foldermeliband copyLICENSE,pyproject.tomlandsetup.cfginto this folder.mkdir melibcd melibcopythe python libraries and thedatafolder intomelibmkdir docsThis is the folder structure at this stage:cd docssphinx-quickstartSeparate 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]: __This creates an intial directory structure as seen below:The next step is to edit the filesindex.rstandconf.py(they are two files sphinx
created in thedocsfolder and are marked in the figure above.
We will also create a new fileapi.rstin the same folder.  Incidentally, the VS Code,
did not automatically update the folder pane aftersphinx-quickstart.  One needs
to refresh to see the new files and folders indocs.index.rstThis is the file after I edit it:.. melib documentation master file, created by
   sphinx-quickstart on Tue Jun  8 09:34:23 2021.

Welcome to melib's documentation!
=================================
The melib package has three files: library, xt, and excel.
The first one is a library of functions that can be used
to do machine element design computations.  It was created
to help teach a second year design course at the University
of Queensland.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   api.rst


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`conf.pyFirst, I add the path for the package files:import os
import sys
sys.path.insert(0, os.path.abspath('..'))Then the extensions.  I copied the extension list from theconffile in thepsf/requestsrepository on github.  I probably did not need them all.  Anyway, here they are.extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.intersphinx",
    "sphinx.ext.todo",
    "sphinx.ext.viewcode",
]api.rstThis is a new file:melib API reference
===================

.. module:: melib

.. automodule:: melib.library
    :members:

.. automodule:: melib.xt
    :members:

.. automodule:: melib.excel
    :members:

The data folder has design data that are needed by the functions in the library.py file.Before running./make htmlto generate the local documentation pages, I copy the
image files I need into theassetsfolder.  These image files are referred to
by doc strings in thelibraryandxtfiles.  For example, the reference to
the fileshoulderscf.pnginlibrary.pyis.. image:: ../../assets/shoulderscf.pngThe local addressing is all with respect to thedocsfolder.This completes the local documentation.  Let us now generate agithubrepository.IMPORTANTMake sure you import themockrepository.  Otherwise,./make htmlwill not work after we do the mock imports of the next section below.  In VS CodePowershellterminal, enterpy -m pip install mockand it will installmockin the python kernel that is used by VS Code.  Incidentally,py -m pipis
always better than justpipbecause it makes sure that the packe is imported into
the python kernek you are using.  Otherwise, confusion may occur when you have multiple
python versions installed on your computer.Construct remote repositorygit add -Agit commit -am'the first commit'git branch -M maingit remote add origin https://github.com/Gurgenci/melib.gitgit push -u origin mainRemote documentationI will generate documentation usingReadtheDocs.  For a package likemelibthat
needs to import other packages, the dependencies need to be stated up front.  Otherwise,ReadtheDocswill fail.I create a new file calledrequirements.txtin thedocsfolder:numpy>=1.0
pylatex>=1.0
openpyxl>=1.0Now add this file to thegitrepository:git add -Agit commit -am 'with the new file requirements.txt'git push -u origin mainLog in toReadtheDocs.orgImport a repository (melib should appear as an available option)
The import click will invoke the following menu.Simply press theNextbutton to get toThen click on theBuild versionbutton.  When theBuildis finished, click
on theView docsbutton.Unfortunately, this did not work.  The document generator failed to import my
fileslibrary,xt, andexceland issued the following warnings:WARNING: autodoc: failed to import module 'library' from module 'melib'; the following exception was raised:
No module named 'numpy'
WARNING: autodoc: failed to import module 'xt' from module 'melib'; the following exception was raised:
No module named 'pylatex'
WARNING: autodoc: failed to import module 'excel' from module 'melib'; the following exception was raised:
No module named 'openpyxl'
looking for now-outdated files... none foundThis was a surprise because I tested the use of arequirements.txtin a
simpler package,hgdemo.  There,ReadtheDocsmanaged to import a module thatreferencednumpyafter I included arequirements.txtfile with anumpyline.This approach did not work formelib.I decided to try an approach suggested inhttp://blog.rtwilson.com/how-to-make-your-sphinx-documentation-compile-with-readthedocs-when-youre-using-numpy-and-scipy/.  The suggestion is to include the following code at the top of theconf.pyfile:import mock

MOCK_MODULES = ['numpy', 'scipy', 'matplotlib', 'matplotlib.pyplot', 'scipy.interpolate',
                'pylatex', 'openpyxl',
                'pylatex.Document',
                ]
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()This made theNo module named 'pylatex'and similar messages disappear from theraw log.
But the documentation still did not include anything onlibrary,xtandexcelcontents.I then realised that it is not enough tomocka package but you need tomockevery module you import from it.  For example, forpylatex.utilsyou getNo module named 'pylatex.utils'; 'pylatex' is not a packageAll packages and its sub-packages must be added to the 'MOCK-MODULES' inconf.py.
The objects imported from those packages do not need to be included inMOCK-MODULES.
For example, if'pylatex.utils' in MOCK_MODULES, then the linefrom openpyxl.utils import get_column_letteris safe.  However,from openpyxl.utils.cell import coordinate_from_stringis not acceptable.  One needs to addopenpyxl.utils.celltoMOCK_MODULESIncidentally, when you do arebuildin ReadtheDocs, you must make sure that ReadtheDocs
is project database is updated with your latestgit push.  Otherwise,Build Docswill fail and it is an ugly process to recover from it.  So make sure that the
time since last built is as you expect it:Sometimes, it takes a relatively long time for this time to reset to your last commit.
Once it was 15 minutes for me.If all works well, the documentation will be created onhttp://hgdemo.readthedocs.io/Upload to PyPiFinally, themelibpackage is uploaded toPyPiso that it can bepipped by others.
This is done through the following process:Start an account withhttps://pypi.org/if you do not have one alreadyOnce you have yourPyPiaccount, create an API token throughhttps://pypi.org/manage/account/(scroll down that page and you will see the section)If you follow thePyPidefaults, this token is stored in$HOME/.pypirc, on my system
the token file name wasC:\Users\e4hgurge\.pypircThe root folder for the following steps is "git/melib" in my system.Create two files in the root folder:setup.cfgandpyproject.toml(see thegithubrepository for the contants of these files)Create a file calledLICENSE(no extensions)I use GNU General Public License (fromhttps://choosealicense.com/).  I
copied the license text to the clipboard on this page and pasted it into the
filesetup.cfg.Increment the version insetup.cfgMake sure that we running the latest version ofpip:py -m pip install --upgrade pipMake sure that we running the latest version ofbuild:py -m pip install --upgrade buildNow runbuildin the root folderpy -m buildThis will generate thedistfolder with the following two files in it:dist\hgdemo-0.0.1-py3-none-any.whldist\hgdemo-0.0.1.tar.gzIf you are using VS Code, refresh the folder pane contents to see the changes.Now runtwineto upload these two files to TestPyPi:py -m twine upload --repository testpypi dist/*This worked.  Now let us do the same for PyPi:py -m twine upload dist/*This sometime givesHTTPError: 400 Bad Request ...Even when you change your version, this sometimes happens.py -m twine upload --skip-existing dist/*sometimes works.Including the data files in PyPi uploadhttps://packaging.python.org/guides/using-manifest-in/lists the following files as those included in a source distribution by default:all Python and C source filesfiles specified inscripts_setup(),package_data, anddata_files setup()license_fileandlicense_filesas specified insetup.cfgall filestest/test*.py,setup.pyand/orsetup.cfgREADME.mdand some otherREADMEextensions, andMANIFEST.in.
I have adatadirectory with five Excel files.  I tried a few things to include them in the PyPi distribution and the following addition tosetup.cfgworked:[options.data_files]
data = melib/data/mats.xlsx, melib/data/bearing.xlsx, melib/data/sgear.xlsx, melib/data/shaft.xlsx,melib/data/vbelt.xlsxI included the files all one line and with no spaces after the commas.  But I do not think this matters.  Incidentally, using wild cars likemelib/data/*.xlsxibstead of listing all five files separately did not work.Final StepsGo to the root directory of the packagegit statusgit add -Agit commit -am "Final Commit for the version 1.0.0 following the pypi upload"git push -u origin mainLog in tohttps://readthedocs.org/dashboard/and clock on the projectmelibClick on [Build Version] after making sure that the last built is the one you
justpushed.  The only way you can tell is by the time (e.g.3 minutes ago).
Refresh the page if necessary.Documentation will be created onhttps://melib.readthedocs.ioAdditional issuesPyPi Upload FailureI have already mentioned the occasional error message:HTTPError: 400 Bad Request from https://upload.pypi.org/legacy/
File already exists. See https://pypi.org/help/#file-name-reuse for more information.This happens when I fail to change the version number insetup.cfg(for example, if I try to upload version 1.0.11 again).  When I change the version number (e.g. 1.0.12), I occasionally still get the same error.  Deleting thedistandmelib.egg-infofolders before thebuildwork in such circumstances.  At the end, I get into the habit of deleting thedistandmelib.eff-infofolders after every upload - just in case.PIP FailureSometimes,pipdecides not to download the new version.  It says that the version I have is already current and no update is needed.  In such instances, deleting the local version always work.I have two python installations: one was generated when I installedanacondaand the other throughVS code.  They are in two separatesite-packagesfolders:...\Anaconda3\Lib\site-packagesand...\.julia\conda\3\Lib\site-packagesI delete bothmelibfolders in both of them because I read somewhere that sometimespipdecides to save on communications bandwidth and installs a local version of the library rather than going toPyPi.  I have not experienced it (I think) but I playe it safe just in case.VS Code and spyderFinally, I do allPyPibuilds andtwineuploading inVS Codeand then go tospyder,pipthe newmeliblibrary and test it there.  I hardly usepythoninVS Code.