Documentation on github?

bernhard

Jeff, I believe you are maintaining the Möbius documentation on github, right?
Would you consider amendment propositions as pull requests?

jeff

They're on github, but they're buried in the middle of the code for the rest of the web site, which is in the same repo as the code for the application. I'd like to move this out into it's own repository to make it easier for collaboration. I'm also struggling with how best to organize the docs. The tools used to look at it, how much of it should be visible inside the app. My concern is that people just don't read docs that are hundreds of pages long. It's too much, and they give up. A lot of it would be better as little chunks that are easier to digest, and some method for searching for it.

There are a lot of tools for this, but they require spending a lot of time on web site design that I really hate doing.

bernhard

So your aim is to use the same source for both the dedicated docs as well as the help docs inside the app?

jeff

Everything would be Markdown docs in github. I found a tool that can render Markdown inside a Juce component for viewing in a popup window in the app. But the in-app docs may need to be abbreviated, without big screen shots, and with a link to the full doc online. We'll see how that goes.

A bigger issue is how to get raw Markdown docs from github into the web site. I use Hugo to turn the Markdown into HTML surrounded by the Hugo template. But Hugo runs on my local machine and I upload the HTML to the site. So it's a multi-step process every time I need to update the docs. What I'd like is if I could use site scripts to periodically pull from github, run Hugo, and leave the HTML results where they need to be. So you could just check in a change on github and a minute later it would appear in the online docs. But this requires a level of shell access and hosted tools I may not be able to get easily.

Unfortunately, what this really needs is a CMS tool which could take months to learn and set up.

SchrodingersCat

jeff Did you consider using Github Pages for the documentation? I think you can set it up from a public repository for no charge. Whenever you make a commit to the main branch of the repository, the Github Pages website gets automatically updated. Github uses Jekyll to build the static website instead of Hugo by default but I think there are ways round that if you don't want to start using it instead. Personally, I'd recommend considering Quarto. (See https://quarto.org/docs/publishing/github-pages.html).

SchrodingersCat

jeff As a follow up to my previous post. I've experimented with setting up GitHub Pages from a GitHub repository using Quarto. I haven't done any of this stuff for about 3 years, so I was a little rusty but I managed to get something working after about a day. I've used my attempts to document emulating the Sheeran Looper X via msl scripts as example content.

My GitHub Pages site can be found at: https://schrodingerscat-mobius.github.io/Mobius3/

I'd appreciate any feedback.

jeff

SchrodingersCat Damn, that's nice! I appreciate all your hard work here. I'm sold on Github Pages. I'm tired of wrestling with self-hosting the docs. I moved the docs (such as they are) to a new Github repo mobius-looper/mobius3-doc and will start building a Github Page around that. The doc repo is public so anyone can contribute, but hold off for awhile until I get things organized.

I'll also be adding a repo for script examples since that's also awkward for me to self-host.

Thanks for the advice!

BTW, what are you using for that spiffy tree navigator on the left? Is that a Jekyl template (or whatever they call it)?

bernhard

There's also this github action to help in automating the process: https://github.com/peaceiris/actions-hugo

SchrodingersCat

jeff I'm using Quarto to render the markdown to html in a docs sub-directory which contains an empty .nojekyll file to stop GitHub Pages doing any additional processing. To get all the fancy stuff like Bootstrap html themes, navigation bars, search etc. I'm just configuring things in a _quarto.yml file in the root of the repo.

If you go to the GitHub repo at https://github.com/SchrodingersCat-Mobius/Mobius3, you can see the source files.
There is a ReadMe that has more details. If you need more info don't hesitate to ask.

One other tip for what it's worth; I've found it helpful to have an overall idea of what kind of hierarchical structure you want the website to have and then organise the source markdown files accordingly. If you are happy to have all of your documentation as a long list you can put all the markdown files in a single directory, but I suspect as the documentation grows that's going to become unworkable.

Did you have something in mind for how the documentation might eventually look?

jeff

I'd like the docs to be written in relatively short easy-to-consume pages. These would then be organized into topics, two or three levels deep.

Getting Started
- The User Interface
- Audio/Midi Devices
- Bindings
  - Functions and Parameters
  - Binding Sets
The Session
- Global Parameters
- Track Parameters
Scripts
- Script Language Basics
- Importing
- Editing
Function Index
- big list-o-functions
Parameter Index
- category
  - parameters
Etc.

So I'd really like a tree navigator on the left, and ideally some kind of search capability.

Thanks for the site source link, I'll have a look at that. When you use Quarto, are you running that on your local machine, then checking in the result to Github? That's what I'm doing now with Hugo, which works, but I'd like to get to where we can just edit the Markdown files, check them in, and have magic happen on Github which I guess would mean Quarto running in Github. Not sure if that's possible. Going through a "compile" step locally isn't terrible but it makes it a little harder for collaboration if everyone needs to know how to do that.

SchrodingersCat

jeff Currently, I'm using Quarto locally because I know how to do that. I think it might be possible to use GitHub actions to run Quarto in GitHub with Quarto being provided via the https://github.com/quarto-dev/quarto-actions repo provided by Quarto's developers.

Let me investigate how it's done and I'll get back to you.

UPDATE: It's looking promising. To save you a bit of work I'm gonna see if I can create a template website as a repo with some instructions which you could then download from GitHub and paste into your doc repo to get you started.

SchrodingersCat

jeff I've made a fork of your mobius-looper/mobius3-doc repo.

I've added the files necessary to create a skeleton website using Quarto and to automate it using GitHub actions.

Hopefully if you do the following steps you should be able to get it working in your repo.

On GitHub, create a new branch of the mobius3-doc repo called gh-pages.
Still within the mobius3-doc repo go to Settings, Code and automation: Pages and then under Build and Deployment make sure Source is set to "Deploy from a branch" and that Branch is set to "gh-pages" and "/(root)" and then click on Save.
Accept my pull request . (This should add .github/workflows/publish.yml, styles.css, index.md, about.md and _quarto.yml to the main branch of the repo.)
Wait several minutes and the site should become live. (The site address is given at the top of the page you were on when you set the Build and Deployment information.)

PS: I've never sent a PR to someone before so I hope I've done it right.

jeff

Thank you so much for this. I've been traveling and haven't had a chance to look at this closely, but I will over the next few days.