Migrate Multipass docs to RTD #3916
Conversation
|
Additional info: The test site on RTD, based on a branch of my forked repo, is here: https://canonical-multipass-docs-migration-test.readthedocs-hosted.com/en/migrate-docs-to-rtd/ The branch of my fork used for this test is: https://github.com/giuliazanchi/multipass/tree/migrate-docs-to-rtd |
Signed-off-by: Giulia Zanchi <[email protected]>
Signed-off-by: Giulia Zanchi <[email protected]>
we have bidirectional streaming rpcs, but we usually send only one response back on that stream for most operations. therefore, the gui would only read data from the stream until it got the first reply. but this introduced errors in which the stream was disposed too early. now we read everything from the stream, so that issue shouldn't happen.
giuliazanchi
force-pushed
the
migrate-docs-to-rtd
branch
from
4961ff1 to
4bb0332
Compare
|
Hi @levkropp , I did a |
Hey @giuliazanchi ! It's looking like |
giuliazanchi
force-pushed
the
migrate-docs-to-rtd
branch
from
f544339 to
4bb0332
Compare
There was a problem hiding this comment.
LGTM @giuliazanchi
Everything seems to work fine and I didn't notice anything broken.
There are a few things I spotted that you might want to consider here or in a future PR, including:
- Amending
conf.pyto add the feedback button - Synchronising tabs on pages with multiple tab blocks
- Removing serial dashes from some page titles and the side nav
I didn't go deep into the content of individual pages but there were no notable problems and all the tests seem to be passing.
|
|
||
| Home <self> | ||
| tutorial/index | ||
| how-to-guides/index |
There was a problem hiding this comment.
| how-to-guides/index | |
| how-to-guides/index | |
| How-to guides <how-to-guides/index> |
I don't think you want titles with multiple dashes like How-to-guides and Command-Line-Interface in the section titles? They weren't in the original MP docs and there is a few of them here.
A change like the one above in docs/index.md enables you to assign the name that will appear in the side navigation (in this case: How-to guides).
Alternatively, you can change the top-level (h1) heading in the how-to-guides/index page, for example, and this should be reflected in the side navigation (as well as the page, of course).
This shouldn't affect the URL.
There was a problem hiding this comment.
Good catch! This is how they came out of the extraction script, I hadn't noticed the dashes in the side navigation. Thanks, I'll fix the H1 titles everywhere.
| Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu. | ||
| ``` | ||
| (install-multipass-prerequisites)= | ||
| ## Check prerequisites |
There was a problem hiding this comment.
In this section, the tab choices are not synchronised within the page. So, someone has to choose, say, macOS each time as they progress downwards.
If you want the tab choice to affect others on this page (and others) with multiple tab blocks:
- replace each
{tab-set}with{tabs}and each{tab-item}with{group-tab}.
| ```{toctree} | ||
| :hidden: | ||
| :titlesonly: | ||
| :maxdepth: 2 | ||
| :glob: |
There was a problem hiding this comment.
| ```{toctree} | |
| :hidden: | |
| :titlesonly: | |
| :maxdepth: 2 | |
| :glob: |
I don't think this is necessary?
A side effect of including this is that in the side panel the Tutorial appears like this: Tutorial v (i.e., with a dropdown arrow). The dropdown suggests that there are multiple tutorials but there is only one.
I removed this toctree block: nothing seemed to break, the dropdown disappeared and the tutorial could be clicked as normal.
|
This PR is now replaced by #3921 to resolve some issues with the commit history |
I moved my comments there. |
This PR adds the /docs/ folder to the repo, including the documentation files in .md format, all the necessary files to build and render the docs in Sphinx, and the starter pack extension.
To test it out, go into the /docs/ folder and run
make cleanand thenmake run, or justmaketo see the available targets.