Fix docs/installation landing page

[matthewcarbone]

The landing page for the docs still has some references to some old requirements files and old dev install instructions.

[st3r4g]

openjournals/joss-reviews#5115

I was about to open a new issue about this, but then I noticed this one already open so I will add a comment here.

Standard development installation describes an editable pip install based on pyproject.toml. Such procedure fails on my system (pip 23.0):

(ggce2) [GGCE 0]$ pip install -e .
Obtaining file:///home/stefano/git/GGCE
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Installing backend dependencies ... done
  Preparing editable metadata (pyproject.toml) ... error
  error: subprocess-exited-with-error
  
  × Preparing editable metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [28 lines of output]
      Traceback (most recent call last):
        File "/home/stefano/tidy/python-venvs/ggce2/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
          main()
        File "/home/stefano/tidy/python-venvs/ggce2/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/home/stefano/tidy/python-venvs/ggce2/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 181, in prepare_metadata_for_build_editable
          return hook(metadata_directory, config_settings)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-h8krvly0/overlay/lib/python3.11/site-packages/flit_core/buildapi.py", line 49, in prepare_metadata_for_build_wheel
          metadata = make_metadata(module, ini_info)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-h8krvly0/overlay/lib/python3.11/site-packages/flit_core/common.py", line 410, in make_metadata
          md_dict.update(get_info_from_module(module, ini_info.dynamic_metadata))
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-h8krvly0/overlay/lib/python3.11/site-packages/flit_core/common.py", line 207, in get_info_from_module
          docstring, version = get_docstring_and_version_via_import(target)
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-h8krvly0/overlay/lib/python3.11/site-packages/flit_core/common.py", line 180, in get_docstring_and_version_via_import
          spec.loader.exec_module(m)
        File "<frozen importlib._bootstrap_external>", line 940, in exec_module
        File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
        File "/home/stefano/git/GGCE/ggce/__init__.py", line 2, in <module>
          from .model import Model  # noqa
          ^^^^^^^^^^^^^^^^^^^^^^^^
        File "/home/stefano/git/GGCE/ggce/model.py", line 7, in <module>
          from ggce.logger import logger
      ModuleNotFoundError: No module named 'ggce'
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

By the way, note that the command in the documentation is missing a hyphen (e instead of -e).

According to this answer, a recent enough pip should implement editable installs from pyproject.toml. The workaround provided in scripts/install.sh installs the required dependencies but is not exactly the same since it does not make the module importable from arbitrary locations (so it cannot strictly be regarded as an installation method).

If we can't manage to fix the editable install from pyproject.toml, the documentation needs to be changed to describe some other method.

[matthewcarbone]

@st3r4g you are correct there is an issue with installing in editable mode. It was a while ago, but for some reason I could not get the standard editable installation to work properly with pyproject.toml. I ran into the issue you are encountering now. Any advice would be appreciated. My solution was this weird hack from scripts/install.sh, which just installs the dependencies. Then one would do something like

import sys
sys.path.append("/path/to/GGCE")
import ggce

to "edit" the project in real time. Not ideal, I know.

[st3r4g]

The editable install succeeds after the following change:

diff --git a/ggce/__init__.py b/ggce/__init__.py
index a495438..eb21738 100644
--- a/ggce/__init__.py
+++ b/ggce/__init__.py
@@ -9,5 +9,5 @@ except ImportError:
     pass
 
 # DO NOT CHANGE ANYTHING BELOW THIS
-__version__ = ...  # semantic-version-placeholder
+__version__ = '0.1.3.dev'
 # DO NOT CHANGE ANYTHING ABOVE THIS

It seems that this "version placeholder" is not correctly handled by flit? I will investigate further how it should be done.

[matthewcarbone]

Before every build, I replace that line with the actual version as found by dunamai (this is my "hack" to avoid using versioneer), so I'd be surprised if that's the only issue. But anyways if you figure out a way I am all ears! Thanks!