Building documentation

[AnthonyAndroulakis]

I set set up a GitHub workflow to build the docs page (GitHub pages still needs to be set up with the documentation branch on this repo, but that can be done later). The GitHub workflow runs the Sphynx build commands in the /docs folder and then deploys the built docs in a new branch called "documentation". GitHub pages then reads the documentation branch.

The GitHub workflow: https://github.com/niivue/ipyniivue/blob/main/.github/workflows/docs.yml
The documentation branch: https://github.com/niivue/ipyniivue/tree/documentation
Hosted docs site on my fork (for testing purposes): https://anthonyandroulakis.github.io/ipyniivue

I decided to use GitHub pages since the niivue docs are in https://niivue.github.io/niivue, so it'd make sense to then have the ipyniivue docs in https://niivue.github.io/ipyniivue.

I am having an issue with the Sphinx documentation on GitHub Pages. Specifically, the CSS is not rendering properly and some files are inaccessible. For example, clicking on "Show Source" at the bottom of the API Reference page leads to a 404 page.

You can view these problems here: https://anthonyandroulakis.github.io/ipyniivue

[AnthonyAndroulakis]

@christian-oreilly

[christian-oreilly]

Thanks @AnthonyAndroulakis

@scott-huberty is that issue familiar to you? Did you encounter a similar issue when working on the doc for the PyLossless project?

[scott-huberty]

I only took a quick look, but it looks like you are using pydata_sphinx_theme. The projects I've worked on that use this template, the structure typically looks like this:

project_root
├── docs
|   ├── make.bat
│   └── Makefile
|   └──build
|   └──source
│   |   ├── index.rst # this is the documentation main entry point
|   |   ├── _static
|   |   └── generated # this is where the built docs are placed by sphinx
|   |       ├── index.rst
│  ├── conf.py # this is your sphinx configuration file
|  ├── examples # where auto sphinx looks for tutorials to build into RST docs
|   |       ├── my_tutorial.py

It looks like your documentation branch just has a lot of sphinx stuff sitting in the root directory. In principle it could be ipyniivue/doc where all this stuff can live, and that can eventually get merged to main.

For css I think you can use a custom css file as long as you point sphinx to it, via the conf.py file.

So if you add a directory css/custom.css to the _static directory, the line to add in conf.py would be something like this:

# user made CSS to customize look
html_css_files = [
    'css/custom.css',
]

@AnthonyAndroulakis, the pydata_sphinx_theme project doesn't have the best documentation IMO - so feel free to take a look at https://github.com/lina-usc/pylossless/tree/main , I'm pretty sure I set some custom css there.

For more complex examples you can look at mne-tools/mne-python, or most of the other packages in the mne-tools account. They all use pydata_sphinx_theme.

[AnthonyAndroulakis]

Thank you for the information. I'll test out ipyniivue docs with that folder structure.

[scott-huberty]

No problem,

If you get stuck on something feel free to ping me and I'll see if I can take a look or make quick commit

[christian-oreilly]

@cdrake Would you mind giving me a screenshot equivalent to this for NiiVue:

I don't have the kind of access to view that, and I expect you do. Just to guide me in how to setup the GitHub pages deployment for IPyNiiVue. It was deactivated (and the deployment workflow was crashing... I am looking into that)

[christian-oreilly]

Nevermind @cdrake, I figured it out! It deploys fine now. I'll check the CSS issue now.

[christian-oreilly]

This resolved. The fix for the issues with the rendering was actually very silly (just needed to add an empty .nojekyll file at the root of the documentation branch, as per https://stackoverflow.com/a/64544659). I also fixed the deployment issues.