Missing Reference to Quickstart

[matthewgilbert]

Since the quickstart page is no longer rendered via sphinx jupyter plugin, this has broken the toctree page reference.

I believe this could potentially be fixed by adding something like the following to doc/source/conf.py

html_extra_path = ['quickstart.html']

but I'm unclear how to fix the sphinx toc to reference an external html file. Some discussion of a similar issue is here

https://stackoverflow.com/questions/49967691/sphinx-link-to-an-internal-file-declared-as-html-extra-path

[matthewgilbert]

@avantgardeam any thoughts on this?

[matthewgilbert]

If there's an easy sphinx fix I think adopting that would be ideal, since the quarto version of the quickstart does look a lot nicer. But if that turns out to not be straightforward, an alternative would be to just upload a new rendering of the reorganized quickstart.ipynb file and revert to using the sphinx-jupyter plugin.

[pedroteles17]

@matthewgilbert, apologies for the late response; I was heading back home.

If you haven't seen it yet, there's a tutorial by Quarto on deploying documents to GitHub Pages. You can likely use quarto publish with --no-render to avoid re-rendering the document. The final command should be quarto publish gh-pages quickstart.qmd --no-render. If this doesn't work, we can find another solution.

[matthewgilbert]

I think this is going to get rid of all the auto generated documentation on the functions though? The idea would be to completely move away from using sphinx?

I think for now maybe the easiest thing would be to just make an additional commit with an updated rendering of the .ipynb file and I can look at integrating quarto when I have a bit more time. Alternatively if you have an idea of how to integrate a pre-rendered quickstart.html with sphinx that would also work.

For reference, the current build system for the docs is in https://github.com/matthewgilbert/blp/blob/master/.github/workflows/release-docs.yml so if you are building the documentation locally this looks like

source hacking/.dev
cd doc
make html
cd build/html
python -m http.server

[avantgardeam]

I think this is going to get rid of all the auto generated documentation on the functions though? The idea would be to completely move away from using sphinx?

I think for now maybe the easiest thing would be to just make an additional commit with an updated rendering of the .ipynb file and I can look at integrating quarto when I have a bit more time. Alternatively if you have an idea of how to integrate a pre-rendered quickstart.html with sphinx that would also work.

For reference, the current build system for the docs is in https://github.com/matthewgilbert/blp/blob/master/.github/workflows/release-docs.yml so if you are building the documentation locally this looks like

source hacking/.dev
cd doc
make html
cd build/html
python -m http.server

@matthewgilbert, I've submitted a PR with the restructured quickstart.ipynb. My apologies for any confusion and trouble caused earlier. I initially believed updating the link in README.md would suffice, but I now understand the broader implications.

[matthewgilbert]

Closed by https://github.com/matthewgilbert/blp/pull/35