How This Package Was Built Using Cookiecutter

The cookiecutter docs are not super easy to follow. Here’s all the steps I did to put this package together.

I’m running on my Mac M4 running Sequoia 15.6.

• Set up a development environment using conda

  • https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html

  • conda create --name myEnv

  • conda activate myEnv

• Installing and setting up cookiecutter

  • conda install pip

  • pip install -U cookiecutter

  • cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage.git

    • Fill out the question prompts

  • This will create a local directory containing their boilerplate code

  • References:

    • https://github.com/audreyfeldroy/cookiecutter-pypackage

    • https://cookiecutter.readthedocs.io/en/stable/README.html#installation

• Writing the package

  • Code:

    • mypackage/src/mypackage/mypackage.py is where all your main functions go

    • You can put other modules in mypackage/src/mypackage and call them from mypackage.py (ie, a utils.py file)

  • Tests:

    • Yes, you do have to write tests for your code

    • mypackage/tests/test_mypackage.py is the main test file

      • you can write separate test_{name}.py test files in this same directory for other submodules

    • pip install pytest

    • then from the top level directory you can run the tests as python -m pytest

• Installing the package:

  • Install locally: pip install . from inside the directory

  • Install locally and editable: pip install -e .

    • You don’t have to re-install every time you change your code

• Using your shiny new package:

  • From a different directory

  from mypackage import mypackage, utils
  utils.do_something_useful()
  x = mypackage.foo()
  

• Writing and building documentation:

  • pip install sphinx

  • cd into mypackage/docs/

  • sphinx-quickstart sets everything up

    • follow prompts

    • I set it up with separate source and build directories - if you don’t you’ll have to change the sphinx-build command

  • cd back up to mypackage/

  • run sphinx-apidoc -o docs/ src/mypackage

    • This will auto-generate the API docs

  • cd back into mypackage/docs/

  • run sphinx-build source build

  • after this point can just run make html every time you want to update the pages

  • you can now open the .html files from build/ in your browser.

  • write some documentation

    • you can link other files’ content into .rst pages using .. include:: ../../README.rst

      • this gave me a ton of grief…just keep messing with it until it does what you want.

  • Docstrings and formatting

    • In conf.py you can add:

    extensions = ['sphinx.ext.napoleon']
    napoleon_google_docstring = False
    napoleon_use_param = False
    napoleon_use_ivar = True
    

    Which just does a nicer job of handling the docstring formatting in more standard Google/NumPy formatting

  • tutorials of use:

    • https://www.sphinx-doc.org/en/master/tutorial/getting-started.html

    • https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/

  • misc

    • https://www.sphinx-doc.org/en/master/usage/theming.html

    • https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#inserting-code-and-literal-blocks

• Hooking into readthedocs

  • Get the repo onto GitHub

    • these directions were useful for me: https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#adding-a-local-repository-to-github-using-git

    • Do NOT put your public access token into your work or you will be bonked when you commit and push

  • Follow the readthedocs instructions: https://docs.readthedocs.com/platform/stable/tutorial/index.html

    • Main thing I ran into: the new .readthedocs.yaml file needs the path to the conf.py file, which for me was in docs/source/conf.py and not the default docs/conf.py

  • voila!

• Other bits and pieces:

  • dependencies (like numpy or matplotlib or what have you) go into pyproject.toml file