Sphinx workflow using the starter pack

[DanRoscigno]

I was following the getting started instructions for sphinx and ran into an issue with the Makefile.

The instructions seem to assume that the Starter Pack is installed, but only the sphinx package is installed, so there is no Makefile.

I am happy to write a PR to fix this, but I wanted to check with you to see what the desired workflow is. I would think that you would want a workflow something like:

• clone the starter pack
• cd into the starter pack
• build and server the starter pack samples
• copy some of the .rst or .md files from the multipass, snapcraft, or wsl folders from the open-documentation-academy repo into the starter pack folder
• add the new folder(s) to index.rst
• make build and examine the structure under the build folder
• make serve

Does this sound correct?

[degville]

@DanRoscigno Thank you so much for suggesting this, and I'm sorry for not responding before now. We've just discussed this briefly, and you're more than welcome to try and improve the getting started instructions.

[giuliazanchi]

Hi @DanRoscigno , I monitor Multipass-related issues and saw your PR: #140 - I think it's a great idea suggesting to use Multipass if you don't have a Linux machine available :) I'll check progress to see how things are working out!

[DanRoscigno]

Hi @DanRoscigno , I monitor Multipass-related issues and saw your PR: #140 - I think it's a great idea suggesting to use Multipass if you don't have a Linux machine available :) I'll check progress to see how things are working out!

Thanks @giuliazanchi , I use multipass or Docker for things like this even though I run on Linux. This ensures that when I write a HowTo I am starting off form the same point as the reader.

[DanRoscigno]

on hold for a bit, waiting for https://github.com/canonical/sphinx-docs-starter-pack/tree/use-canonical-sphinx-extension to be merged into main

See: canonical/sphinx-docs-starter-pack#282 (comment)

[DanRoscigno]

Good news, the above "on hold" branch has been renamed to main in the starter pack repo. I will complete this issue ASAP.

on hold for a bit, waiting for https://github.com/canonical/sphinx-docs-starter-pack/tree/use-canonical-sphinx-extension to be merged into main

See: canonical/sphinx-docs-starter-pack#282 (comment)