[EPIC] Port existing Hub Service Guide content to Jupyter Book about docs HOT 8 OPEN

Exploratory work

• Initial build partially successful in #209 with a basic _config.yml – does not contain any custom content from the original conf.py and there are currently a lot of warnings
• How do we implement the top navigation bar pointing to the Infrastructure guide, Support and social links?

from docs.

• How do we implement the top navigation bar pointing to the Infrastructure guide, Support and social links?

Ah! I think this is achieved by using https://github.com/2i2c-org/sphinx-2i2c-theme

from docs.

Ah! I think this is achieved by using https://github.com/2i2c-org/sphinx-2i2c-theme

Correct :-)

If it's helpful, I'm happy to do a quick runthrough of the tech with you this week. Lemme know if that could save you some exploration time. Alternatively, if there is information you'd find useful that I could record in a write-up or a short video, let me know and I can do that asynchronously and share

from docs.

@choldgraf I made a fair amount of progress today and getting to grips with the tech! Thank you for the offer, I'll make sure to let you know if I come up against anything, but so far so good.

(I especially enjoy your breadcrumbs of knowledge spread throughout the internet, e.g. https://chrisholdgraf.com/blog/2022/sphinx-custom-crossrefs/) 😆

from docs.

hah glad you found that useful :-) I miss writing blog posts like that!

One word of advice: don't get too creative with Sphinx, because if we want to transition things to mystmd.org at some point, we don't want to have too much Sphinx-specific logic. I know that I've already built a bunch of sphinx-specific logic into the websites already and I regret it because it makes the sites harder to understand and maintain!

from docs.

I had a great chat with @agoose77, who provided a lot of clarity around some small questions that I had. The main outcome of the conversation is captured in #212.

from docs.

Exploratory work

• Regarding the main concern around getting the FreshDesk widget to work, I managed to do this in a custom.js file in commit 815b00f 🥳
• There are a few broken links to images hosted on GDrive related to their phase out of third party cookies. The recommendation is to use iFrames instead, but I have opted to upload the images to a folder in this repo in commit cdb94af

from docs.

Exploratory work

• I ran jupyter-book build --builder linkchecker and fixed all of the errors by either fixing the stale link "upstream" in our Google Drive https://github.com/2i2c-org/meta/issues/941 or amending out-of-date content. My next step is to upstream this to our 2i2c-org .github/workflows and incorporate this into the CI/CD
• I moved the custom scripts from conf.py into the scripts folder and these will be run during CI/CD pre-build phase. I tried executing this code in Jupyter Notebooks at first within the jupyter build command (à la the Jupyter Book docs), but the CSV file generated for the feature table was not detected by the rest of the build process, so the csv-table in about/distributions/index.md failed.
• I have customised .readthedocs.yml to generate a preview using jupyter-book build rather than sphinx-build 👍

from docs.