Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Sphinx workflow using the starter pack #123

Open
DanRoscigno opened this issue Aug 9, 2024 · 5 comments · May be fixed by #140
Open

Sphinx workflow using the starter pack #123

DanRoscigno opened this issue Aug 9, 2024 · 5 comments · May be fixed by #140
Assignees
@DanRoscigno
Labels
size 2 Fix a known documentation issue (size 2/8) update Update potentially outdated instructions, commands, or version numbers

Comments

@DanRoscigno
Copy link
Contributor

DanRoscigno commented Aug 9, 2024 •
edited
Loading

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
Copy link
Collaborator

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

@degville degville added size 2 Fix a known documentation issue (size 2/8) update Update potentially outdated instructions, commands, or version numbers labels Sep 13, 2024
@DanRoscigno DanRoscigno linked a pull request Sep 14, 2024 that will close this issue
Draft
2 tasks
@giuliazanchi
Copy link
Collaborator

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
Copy link
Contributor Author

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
Copy link
Contributor Author

DanRoscigno commented Oct 4, 2024 •
edited
Loading

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
Copy link
Contributor Author

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@DanRoscigno DanRoscigno

Labels
size 2 Fix a known documentation issue (size 2/8) update Update potentially outdated instructions, commands, or version numbers
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

DRAFT using Multipass DanRoscigno/open-documentation-academy
3 participants
@degville @giuliazanchi @DanRoscigno