Fail to build docs locally

[jsheunis]

After local installation of requirements for the docs, I try to build it but get an error

> make -C docs html

Application error:
Cannot find source directory (/Users/jsheunis/Documents/psyinf/pybci/docs/source)
make: *** [html] Error 2

Looks like the docs don't follow a standard layout expected with a sphinx setup. The content should all be in a source directory, or the default source directory that sphinx looks for should be changed. I haven't looked at why readthedocs build doesn't fail because of this, perhaps rtd does some internal corrections before building.

I want to do a PR to check the CI run in any case, so I'll do a PR to fix this issue. Then we'll see if rtd also build correctly after the layout change.

[jsheunis]

After moving content to a source directory, the build works fine, apart from several warnings.

new layout:

> tree docs

docs
├── Makefile
├── make.bat
├── requirements.txt
└── source
    ├── BackgroundInformation
    │   ├── Contributing.rst
    │   ├── Epoch_Timing.rst
    │   ├── Examples.rst
    │   ├── Feature_Selection.rst
    │   ├── Getting_Started.rst
    │   ├── Pseudo_Device.rst
    │   ├── Theory_Operation.rst
    │   └── What_is_PyBCI.rst
    ├── Images
    │   ├── flowchart
    │   │   └── Flowchart.svg
    │   ├── operation.svg
    │   ├── pyBCI.png
    │   ├── pyBCITitle.png
    │   ├── pyBCITitle.svg
    │   └── splitEpochs
    │       ├── example1.png
    │       ├── example1split0.png
    │       └── example1split50.png
    ├── api
    │   ├── Configurations.rst
    │   ├── LSLScanner.rst
    │   ├── PseudoDevice.rst
    │   ├── PseudoDeviceController.rst
    │   └── PyBCI.rst
    ├── conf.py
    └── index.rst

Building the docs from the repo root directory:

> make -C docs html

Running Sphinx v7.2.6
WARNING: html_static_path entry '_static' does not exist
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 2 source files that are out of date
updating environment: 0 added, 2 changed, 0 removed
reading sources... [100%] index
/Users/jsheunis/Documents/psyinf/pybci/docs/source/BackgroundInformation/Getting_Started.rst:29: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/Users/jsheunis/Documents/psyinf/pybci/docs/source/BackgroundInformation/Getting_Started.rst:44: WARNING: Title underline too short.

Optional: Virtual Environment
----------------------------
/Users/jsheunis/Documents/psyinf/pybci/docs/source/BackgroundInformation/Getting_Started.rst:71: WARNING: Title underline too short.

Simple Implementation:
===================
/Users/jsheunis/Documents/psyinf/pybci/docs/source/BackgroundInformation/Getting_Started.rst:71: WARNING: Title underline too short.

Simple Implementation:
===================
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... WARNING: unsupported theme option 'github_user' given
WARNING: unsupported theme option 'github_repo' given
WARNING: unsupported theme option 'github_button' given
done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 8 warnings.

[jsheunis]

Ping: https://github.com/openjournals/joss-reviews/issues/5706

[LMBooth]

Thank you for identifying this @jsheunis and providing a fix, i wasn't aware of the required structure - i just let it build via readthedocs every time.