Developer instructions lead to error messages

[nutjob4life]

Checked for duplicates

Yes - I've already checked

🐛 Describe the bug

When following the instructions for developers at https://nasa-pds.github.io/pds-api-client/developer/index.html I encountered several error messages.

🕵️ Expected behavior

I expected the developer instructions to succeed without errors.

📜 To Reproduce

The instructions in the developer docs don't seem to work without several modifications—and even then, end in error. Following along, I tried the following:

$ cd /tmp
$ git clone https://github.com/NASA-PDS/pds-api-client.git
Cloning into 'pds-api-client'...
remote: Enumerating objects: 1458, done.
remote: Counting objects: 100% (264/264), done.
remote: Compressing objects: 100% (136/136), done.
remote: Total 1458 (delta 156), reused 165 (delta 110), pack-reused 1194 (from 1)
Receiving objects: 100% (1458/1458), 4.43 MiB | 9.74 MiB/s, done.
Resolving deltas: 100% (876/876), done.
$ git pull
fatal: not a git repository (or any of the parent directories): .git

There probably should be a cd pds-api-client before the git pull command.

$ cd pds-api-client
$ git pull
Already up to date.

The instructions then say to run

pip install pyyaml

But this would install it into the system Python; a virtual environment should be used instead:

$ pwd
/tmp/pds-api-client
$ python3.13 -m venv .venv
$ . .venv/bin/activate
(.venv) $ pip install pyyaml
Collecting pyyaml
  Using cached PyYAML-6.0.2-cp313-cp313-macosx_11_0_arm64.whl.metadata (2.1 kB)
Using cached PyYAML-6.0.2-cp313-cp313-macosx_11_0_arm64.whl (171 kB)
Installing collected packages: pyyaml
Successfully installed pyyaml-6.0.2
$ rm -fr pds test
$ python src/pds/api_client/preprocess_openapi.py /Users/loubrieu/PycharmProjects/pds-api/specs/PDS_APIs-search-1.1.1-swagger.yaml --version 1.3.0
Traceback (most recent call last):
  File "/private/tmp/pds-api-client/src/pds/api_client/preprocess_openapi.py", line 77, in <module>
    main()
    ~~~~^^
  File "/private/tmp/pds-api-client/src/pds/api_client/preprocess_openapi.py", line 66, in main
    with open(args.input_yaml, "r") as stream:
         ~~~~^^^^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: '/Users/loubrieu/PycharmProjects/pds-api/specs/PDS_APIs-search-1.1.1-swagger.yaml'

Here, we're trying to reference a swagger.yaml file that doesn't exist. The instructions probably should recommend downloading a copy of swagger.yaml from GitHub:

(.venv) $ curl --silent --location --output swagger.yaml 'https://github.com/NASA-PDS/pds-api/raw/refs/heads/main/specs/PDS_APIs-search-1.6.0-swagger.yaml'
(.venv) $ python3 src/pds/api_client/preprocess_openapi.py --version 1.6.0 swagger.yaml
[main] INFO  o.o.codegen.DefaultGenerator - Generating with dryRun=false
[main] INFO  o.o.c.ignore.CodegenIgnoreProcessor - No .openapi-generator-ignore file found.
[main] INFO  o.o.codegen.DefaultGenerator - OpenAPI Generator: python (client)
…
################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
################################################################################

Finally, the instructions recommend modifying the setup.py file; note that on the page at https://nasa-pds.github.io/pds-api-client/developer/index.html the modifications are shown in proportional font and with paired quotes and apostrophes that need to be replaced with straight quotes and apostrophes.

The modified setup.py file ends up being as follows:

(.venv) $ diff -bu setup.py.orig setup.py
--- setup.py.orig	2025-08-27 09:56:59
+++ setup.py	2025-08-27 09:59:08
@@ -14,7 +14,9 @@
 
 
 from setuptools import setup, find_packages  # noqa: H301
+from setuptools import find_namespace_packages
 
+
 # To install the library, run the following
 #
 # python setup.py install
@@ -40,7 +42,8 @@
     url="",
     keywords=["OpenAPI", "OpenAPI-Generator", "PDS Registry Search API"],
     install_requires=REQUIRES,
-    packages=find_packages(exclude=["test", "tests"]),
+    packages=find_namespace_packages(where='src/', exclude=["test", "tests"]),
+    package_dir={"": "src"},
     include_package_data=True,
     license="Apache 2.0",
     long_description_content_type='text/markdown',

Finally, we're told to run tox to run the tests; however, tox was not installed in the virtual environment; installing it and then running it gives the following:

(.venv) $ pip install tox
GLOB sdist-make: /private/tmp/pds-api-client/setup.py
py3 create: /private/tmp/pds-api-client/.tox/py3
…
======================================================== ERRORS ========================================================
_______________________ ERROR collecting src/pds/api_client/test/integration/test_collections.py _______________________
ImportError while importing test module '/private/tmp/pds-api-client/src/pds/api_client/test/integration/test_collections.py'.
Hint: make sure your test modules/packages have valid Python names.

The error message is repeated several times but for other test files, perhaps something to do with namespace packages? I'm not sure, as I need to move onto another task.

Hope this enough to get started! 🏎️💨

🖥 Environment Info

• pds-api-client main branch pulled on 2025-08-27

📚 Version of Software Used

• Python 3.13

🩺 Test Data / Additional context

No response

🦄 Related requirements

🦄 #xyz

⚙️ Engineering Details

No response

🎉 Integration & Test

No response