conventional installation instructions, python packaging

[brandondube]

This issue is part of my portion of the JOSS review, openjournals/joss-reviews#5478

Ordinarily, python packages contain an installation heading on their main documentation page. The PyPO docs require that I navigate from the index to "Related Pages" (a guess) and then the "General" page includes installation instructions.

Please place installation instructions on the index page of the documentation

--

The build instructions are highly non-normative for python, there is an ongoing multi-year period of confusion with python packaging, between poetry, pyproject.toml, setup.cfg/setup.py, and so on. Regardless of all of that, the software should be installable using a one of the usual methods:

• pip install . or pip install https://github.com/PyPO-dev/PyPO
• poetry add PyPO

and so on. This will require that you make a setup.py file, and/or setup.cfg+setup.py, or pyproject.tml file.

The user should not need to edit environment variables, and you should especially not prescribe path editing methods. For example, I do not not even have $PYTHONPATH set; your instructions are incompatible with my ordinary, conda-based python environment

--

As-is, the instructions provide no feedback as to whether they worked or not; I ran ./Build.py -f and then -m, which opened a new terminal for a brief moment with no feedback as to whether it worked or crashed. Same for -t.

[arendMoerman]

Hi @brandondube, sorry for the long wait, I had a lot of stuff to prepare for because of a conference I had on Monday this week.

We pushed a new version to the main branch, which should be properly installable using pip.
The installation instructions now reflect this and are placed on the index page of the docs as per your comments.

Does this satisfy the JOSS requirements for installation and installation instructions?

I have already reserved a name for PyPO on PyPi (PyPO-pkg), but as of now, it only contains the current sdist of PyPO-pkg_1.0.0.
Is it OK if I wait with generating wheels until after the JOSS review?

[brandondube]

I created a scratch environment for python 3.10 on an M2 macbook air, Ventura 13.3.1(a). The installation instructions did not work:

conda create -n tmp python=3.10
conda activate tmp
pip install -e .
Obtaining file:///Users/bdd/src/PyPO
  Preparing metadata (setup.py) ... done
Collecting numpy
  Downloading numpy-1.24.3-cp310-cp310-macosx_11_0_arm64.whl (13.9 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 13.9/13.9 MB 14.0 MB/s eta 0:00:00
Collecting scipy
  Downloading scipy-1.10.1-cp310-cp310-macosx_12_0_arm64.whl (28.8 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 28.8/28.8 MB 25.0 MB/s eta 0:00:00
Collecting matplotlib
  Downloading matplotlib-3.7.1-cp310-cp310-macosx_11_0_arm64.whl (7.3 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.3/7.3 MB 17.4 MB/s eta 0:00:00
Collecting pillow>=6.2.0
  Downloading Pillow-9.5.0-cp310-cp310-macosx_11_0_arm64.whl (3.1 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.1/3.1 MB 36.8 MB/s eta 0:00:00
Collecting contourpy>=1.0.1
  Downloading contourpy-1.0.7-cp310-cp310-macosx_11_0_arm64.whl (229 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 229.7/229.7 kB 29.5 MB/s eta 0:00:00
Collecting kiwisolver>=1.0.1
  Downloading kiwisolver-1.4.4-cp310-cp310-macosx_11_0_arm64.whl (63 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 63.2/63.2 kB 3.8 MB/s eta 0:00:00
Collecting cycler>=0.10
  Downloading cycler-0.11.0-py3-none-any.whl (6.4 kB)
Collecting python-dateutil>=2.7
  Downloading python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 247.7/247.7 kB 35.6 MB/s eta 0:00:00
Collecting packaging>=20.0
  Downloading packaging-23.1-py3-none-any.whl (48 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 48.9/48.9 kB 7.7 MB/s eta 0:00:00
Collecting fonttools>=4.22.0
  Downloading fonttools-4.39.4-py3-none-any.whl (1.0 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.0/1.0 MB 37.5 MB/s eta 0:00:00
Collecting pyparsing>=2.3.1
  Downloading pyparsing-3.0.9-py3-none-any.whl (98 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 98.3/98.3 kB 12.7 MB/s eta 0:00:00
Collecting six>=1.5
  Using cached six-1.16.0-py2.py3-none-any.whl (11 kB)
Installing collected packages: six, pyparsing, pillow, packaging, numpy, kiwisolver, fonttools, cycler, scipy, python-dateutil, contourpy, matplotlib, PyPO-pkg
  Running setup.py develop for PyPO-pkg
    error: subprocess-exited-with-error

    × python setup.py develop did not run successfully.
    │ exit code: 1
    ╰─> [41 lines of output]
        running develop
        /Users/bdd/miniconda3/envs/tmp/lib/python3.10/site-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
        !!

                ********************************************************************************
                Please avoid running ``setup.py`` and ``easy_install``.
                Instead, use pypa/build, pypa/installer, pypa/build or
                other standards-based tools.

                See https://github.com/pypa/setuptools/issues/917 for details.
                ********************************************************************************

        !!
          easy_install.initialize_options(self)
        /Users/bdd/miniconda3/envs/tmp/lib/python3.10/site-packages/setuptools/_distutils/cmd.py:66: SetuptoolsDeprecationWarning: setup.py install is deprecated.
        !!

                ********************************************************************************
                Please avoid running ``setup.py`` directly.
                Instead, use pypa/build, pypa/installer, pypa/build or
                other standards-based tools.

                See https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html for details.
                ********************************************************************************

        !!
          self.initialize_options()
        running egg_info
        creating src/PyPO_pkg.egg-info
        writing src/PyPO_pkg.egg-info/PKG-INFO
        writing dependency_links to src/PyPO_pkg.egg-info/dependency_links.txt
        writing requirements to src/PyPO_pkg.egg-info/requires.txt
        writing top-level names to src/PyPO_pkg.egg-info/top_level.txt
        writing manifest file 'src/PyPO_pkg.egg-info/SOURCES.txt'
        reading manifest file 'src/PyPO_pkg.egg-info/SOURCES.txt'
        reading manifest template 'MANIFEST.in'
        adding license file 'LICENSE'
        writing manifest file 'src/PyPO_pkg.egg-info/SOURCES.txt'
        running build_ext
        cmake /Users/bdd/src/PyPO -DCMAKE_LIBRARY_OUTPUT_DIRECTORY=/Users/bdd/src/PyPO/src/PyPO "-DCMAKE_BUILD_TYPE=Release --j4"
        error: command 'cmake' failed: No such file or directory
        [end of output]

    note: This error originates from a subprocess, and is likely not a problem with pip.
error: subprocess-exited-with-error

× python setup.py develop did not run successfully.
│ exit code: 1
╰─> [41 lines of output]
    running develop
    /Users/bdd/miniconda3/envs/tmp/lib/python3.10/site-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
    !!

            ********************************************************************************
            Please avoid running ``setup.py`` and ``easy_install``.
            Instead, use pypa/build, pypa/installer, pypa/build or
            other standards-based tools.

            See https://github.com/pypa/setuptools/issues/917 for details.
            ********************************************************************************

    !!
      easy_install.initialize_options(self)
    /Users/bdd/miniconda3/envs/tmp/lib/python3.10/site-packages/setuptools/_distutils/cmd.py:66: SetuptoolsDeprecationWarning: setup.py install is deprecated.
    !!

            ********************************************************************************
            Please avoid running ``setup.py`` directly.
            Instead, use pypa/build, pypa/installer, pypa/build or
            other standards-based tools.

            See https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html for details.
            ********************************************************************************

    !!
      self.initialize_options()
    running egg_info
    creating src/PyPO_pkg.egg-info
    writing src/PyPO_pkg.egg-info/PKG-INFO
    writing dependency_links to src/PyPO_pkg.egg-info/dependency_links.txt
    writing requirements to src/PyPO_pkg.egg-info/requires.txt
    writing top-level names to src/PyPO_pkg.egg-info/top_level.txt
    writing manifest file 'src/PyPO_pkg.egg-info/SOURCES.txt'
    reading manifest file 'src/PyPO_pkg.egg-info/SOURCES.txt'
    reading manifest template 'MANIFEST.in'
    adding license file 'LICENSE'
    writing manifest file 'src/PyPO_pkg.egg-info/SOURCES.txt'
    running build_ext
    cmake /Users/bdd/src/PyPO -DCMAKE_LIBRARY_OUTPUT_DIRECTORY=/Users/bdd/src/PyPO/src/PyPO "-DCMAKE_BUILD_TYPE=Release --j4"
    error: command 'cmake' failed: No such file or directory
    [end of output]

note: This error originates from a subprocess, and is likely not a problem with pip.

This is just a case of cmake not being installed on my machine; please move the text in the installation instructions about cmake to a more central heading; it is present for windows and linux, but not mac

After the cmake dependency is listed generally, I am satisfied with the installation instructions

There is no problem waiting to generate wheels, or post the package to PyPI; these are not required at all, but are nice conveniences for users who may not wish to install directly from github

[arendMoerman]

Thank you for the comment!
I have now included a prerequisites subsection to the "install from source" section where I explicitly mention that cmake has to be pip-installed before building from source, irrespective of operating system.

This afternoon, we will merge with the main branch again. When you resume the review, can you let us know if the installation instructions work? If it all works, I will close this issue.

[brandondube]

Everything works as-is; you may consider removing the "Irrespective of operating system" note, since it does not add new information

thanks!