Documentation: Pip installable environment and build instructions

[h-mayorquin]

As we did for the testing, I am adding a pip installable environment for the documentation. Also, adding instructions in how to build the documentation locally to the readme file.

Edit:
This is failing the build in read the docs. @CodyCBakerPhD, @bendichter can I get admin rights over there to check and understand the build process? This will also be useful for #495 .

[bendichter]

looks great

[CodyCBakerPhD]

The traceback at https://readthedocs.org/projects/nwb-conversion-tools/builds/16820312/ has the entire collection of workflow actions and outputs, which cannot be altered.

The only thing we can control as far as dependencies is what goes into the requirement-rtd.txt folder, which it uses when calling pip install -r requirements-rtd.txt right before pip install .

We can technically allow access to the 'global site-packages' on readthedocs, which is essentially all of the most recent versions of the most common deps, but I advise against this since it can cause many dependency conflicts. We can also disable the installation of the package altogether, but that seems the opposite of what we want to do here.

[CodyCBakerPhD]

@h-mayorquin So basically, if you want to fix the docs build (necessary before merging), I'd suggest restoring the state of the requirements-rtd.txt, which has been configured to what the readthedocs CI currently requires.

Note that as of today the ephy testing data issued a new hash which triggered cache updates, which triggered an issue with the MacOS latest version of git-annex. Some basic attempts to fix it have failed so I'll just raise an issue and work on it elsewhere - temporarily disabling full tests on Mac until then.

[h-mayorquin]

The traceback at https://readthedocs.org/projects/nwb-conversion-tools/builds/16820312/ has the entire collection of workflow actions and outputs, which cannot be altered.

Yup, I am aware of this.

The only thing we can control as far as dependencies is what goes into the requirement-rtd.txt folder, which it uses when calling pip install -r requirements-rtd.txt right before pip install .

We can technically allow access to the 'global site-packages' on readthedocs, which is essentially all of the most recent versions of the most common deps, but I advise against this since it can cause many dependency conflicts. We can also disable the installation of the package altogether, but that seems the opposite of what we want to do here.

So in the advanced seetings, we have requirements file pointed to requirements-rdt.txt. Do we have the install project option activated?

By looking at the trace it seems that we do.

[h-mayorquin]

@h-mayorquin So basically, if you want to fix the docs build (necessary before merging), I'd suggest restoring the state of the requirements-rtd.txt, which has been configured to what the readthedocs CI currently requires.

Check out the configuration file that I added.

nwb-conversion-tools/.readthedocs.yaml

Lines 23 to 29 in 1d35fa7

	python:
	install:
	- requirements: requirements-minimal.txt
	- method: pip
	path: .
	extra_requirements:
	- docs

It seems that it gives us enough control of the build so we can reproduce what we do locally. This does not require access to the global site-packages which is what you wanted to avoid.

I think this is good because it allows us to eliminate the hard-coded duplication of dependencies that we had in requirements-rdt.txt. That is, we only need to specify the dependencies in the requirements-minimal.txt avoiding duplication.

Note that as of today the ephy testing data issued a new hash which triggered cache updates, which triggered an issue with the MacOS latest version of git-annex. Some basic attempts to fix it have failed so I'll just raise an issue and work on it elsewhere - temporarily disabling full tests on Mac until then.

Is always the MacOS, eh?