Installation instructions are not entirely clear, and come back with issues about incompatible libraries in python 11

[jordanpadams]

💡 Description

From a user:

1) there is one incomplete section in "Usage"; 2) there are inconsistencies between sections; 3) there is some fairly sloppy typing in some key places where the text was clearly never even read over by the author, let alone anyone else.

> python3 -V
Python 3.11.5

There seem to be a lot of errors related to libraries being a later version than expected for some reason, like this one:

conda-repo-cli 1.0.75 requires clyent==1.2.1, but you have clyent 1.2.2 which is incompatible.

As well as some dependency mismatches in the other direction (expects newer, finds older). I was expecting them all to be either too old or too new. How you end up with incompatible dependencies in both directions I couldn't begin to guess. Is all of this code being maintained? Is any of it? Does it depend on a specific distribution of python3?

Most puzzling, I have no idea what the install process thinks it actually "succeeded" in doing when it ultimately declared "Success" The Installation instructions strangely direct me to run the install inside the hidden directory ".venv", which does then contain a subdirectory called "pds-doi-service", but inside that all I see is this:

icarus> pwd
/path/to/venv/pds-doi-service
icarus> ls
total 4
drwxrwxr-x. 2 raugh comets 168 May  2 17:58 bin
drwxrwxr-x. 3 raugh comets  24 May  2 17:58 include
drwxrwxr-x. 3 raugh comets  24 May  2 17:58 lib
lrwxrwxrwx. 1 raugh comets   3 May  2 17:58 lib64 -> lib
-rw-rw-r--. 1 raugh comets 253 May  2 17:58 pyvenv.cfg
icarus>

And the bin/ directory here only contains activation scripts, which an earlier box on the installation page says should not be used. When I attempt to determine where the pds_doiservice.ini file should be created using the method on the Installation page, it tells me I need to install it in the (protected) system directories, which more than defeats the purpose of creating a virtual environment.

⚔️ Parent Epic / Related Tickets

No response

[acraugh]

Here are some specific notes about differences between the installation/configuration directions and what I needed to do to get things to work on my RHEL 8 workstation.

In the Installation section:

• As noted previously, there is an undocumented dependency on libxml2 2.9.2 or later, and libxslt 1.1.28 or later.
• For the libxslt requirement, is it necessary that development headers also be installed.
• If working within a virtual environment, either the venv needs to be activated via the script, or the version of pip3 in the venv needs to be invoked explicitly for the pds-doi-service install step.
• The blue-box note about "activating" the virtual environment might be true for the pds-doi-service itself (that remains to be seen), but it is not true (as noted above) for installation. It also is the opposite of the Python philosophy, since activating a virtual environment is an explicit (https://www.merriam-webster.com/dictionary/explicit) act, whereas having code do it surreptitiously out of sight and knowledge of the end user is definitely implicit (https://www.merriam-webster.com/dictionary/implicit) from the end-user point of view. I also can't find a reference that expresses this same opinion anywhere else on the web, so I'm wondering where it came from. A statement like this needs an attribution for coders to follow up.

In the Configuration section:

• The command to locate the configuration file is not correct for a venv setup - in that case the user must again either activate the virtual environment or specifically invoke the version of python in the venv bin/ directory to get the correct location.
• There is a nearly invisible link with only the text "here" that links to the current conf.default.ini file. A better formulation for this sentence would be "Here is a link to the conf.default.ini file in the doi-service repo." But that's not actually an example of a file to override the conf.default.ini file.
• The presentation of the conf.default.ini file as an example of file intended to override itself is misleading and presents a user with way more complication than they would typically need to deal with to configure the service. It would be simpler to supply an inline example of a file that contains fields that you would expect a typical user to want to override. I can't actually tell what those might be, because there is no documentation for the requirements and constraints on any of the fields in config.default.ini.
• The description of how to create the local config file talks about "updating" rather than "writing" or "adding lines", further implying an implementor should edit config.default.ini rather the create a separate file elsewhere.
• There is no documentation for the content of the configuration file, which is critical for running the application. It is not clear how much of the formatting (like the "[OTHER]" line) is required, whether commenting is possible, what to do if more than one doi_prefix is needed, how significant the version of the PDS JSON schema is, what effect "validate_against_schema" has, and so on. I am frankly afraid to run this code without that knowledge.

In the Running the Service section:

• The pds-doi-cmd (and its siblings) command cannot be invoked from the command line unless it is in the user's path. Might seem obvious, but it is another one of those assumptions about an operating environment that should not be taken for granted in the general case.

I could not test whether the command ran properly without explicitly activating the venv, or indeed at all, because of the lack of documentation for the configuration file fields. I did not attempt to start the API because I'm working remotely and can't access any servers running on the remote machine because of University firewall rules. I would be hesitant to do that without the configuration file documentation in any event.