Building documentation about ipyniivue HOT 8 CLOSED

@christian-oreilly

from ipyniivue.

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?

from ipyniivue.

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.

from ipyniivue.

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

from ipyniivue.

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

from ipyniivue.

@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)

from ipyniivue.

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

from ipyniivue.

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.

from ipyniivue.