Skip to content
This repository has been archived by the owner on Dec 7, 2023. It is now read-only.

Add a Read The Docs website: ignite.readthedocs.org #246

Merged
merged 29 commits into from
Aug 1, 2019
Merged

Add a Read The Docs website: ignite.readthedocs.org #246

merged 29 commits into from
Aug 1, 2019

Conversation

dholbach
Copy link
Contributor

@dholbach dholbach commented Jul 30, 2019 •
edited by luxas
Loading

Re-use some of the work for flux, targetting #207.
Fixes: #207

TODO:

  • include api/ - currently not indexed, as it's not inside docs/ (linking to GH right now)
  • register ignite on readthedocs and import
  • fix videos (Videos (e.g. in "How to use Ignite to run VMs") have their link visible next to the thumbnail, it might be good to just have the thumbnail as the chapters above each video explain them)
  • fix bare URLs in changelog docs

@twelho twelho added kind/documentation Categorizes issue or PR as related to documentation. kind/enhancement Categorizes issue or PR as related to improving an existing feature. kind/feature Categorizes issue or PR as related to a new feature. priority/important-longterm Important over the long term, but may not be staffed and/or may need multiple releases to complete. area/UX Let's make Ignite's UX great! and removed kind/feature Categorizes issue or PR as related to a new feature. labels Jul 30, 2019
@dholbach
Copy link
Contributor Author

If you want to test it, just pull it and run make serve-docs and point your browser to http://localhost:8000/_build/html/index.html.

luxas and others added 19 commits July 31, 2019 13:55
@luxas
Add a Close() method to Storage
20e48ba
@luxas
Factor the network plugin interface out to its own package
258dbff
@luxas
Refactor pkg/providers to not vendor unnecessary stuff
42d1a01
@luxas
Use the new Providers location
959e75d
Start off read-the-docs effort for documentation
dbdd916 
	Re-use some of the work for flux, targetting #207
@luxas
merge with master
d6805b6
@twelho
Merge pull request #252 from luxas/refactor_providers
b1d3997 
Refactor pkg/providers
Fix docs index in a lot of places
8b6f355 
	TODO:
	- link to api docs not working as outside of doctree
	- some docs not referenced from toctrees
		docs/devel.md
		docs/installation.md
		docs/releases/v0.1.0.md
		docs/releases/v0.2.0.md
		docs/releases/v0.3.0.md
		docs/releases/v0.4.0.md
		docs/releases/v0.4.0-rc.1.md
		docs/releases/v0.4.1.md
		docs/releases/v0.4.2.md
	- some backreferences to docs/cli/ignite not working:
		docs/cli/ignite_start.md
		docs/cli/ignite_stop.md
		docs/cli/ignite_version.md
		docs/cli/ignite_vm.md
@luxas
Make it possible to directly patch a file using the library
3acf211
@luxas
Stop patching the annotation to the VM object when starting it; mount…
5cc8590 
… the metadata.json file into /vm.json
@luxas
Stop using the client in ignite-spawn, instead decode /vm.json "by hand"
cd21c03
@twelho
Merge pull request #257 from luxas/spawn_simple_storage
cf77289 
Do not use the Storage/Client in ignite-spawn
break up toctree and make it more readable
c2651b9
@luxas
Activate v1alpha2 in the scheme
82418cd
working with sphinx
fbc15c8
@twelho
Merge pull request #259 from luxas/activate_v1alpha2
bc92e70 
Activate v1alpha2 in the scheme
fix SEE ALSO sections
048831e
move FAQ to be included in docs too
50a110e
fix headings
bae76d5
@dholbach
Copy link
Contributor Author

Screenshot from 2019-07-31 16-44-46

@twelho
Copy link
Contributor

twelho commented Jul 31, 2019 •
edited
Loading

This is defintely the right direction, it looks good! 🎉
A couple of things I noticed when running the docs locally:

  • Videos (e.g. in "How to use Ignite to run VMs") have their link visible next to the thumbnail, it might be good to just have the thumbnail as the chapters above each video explain them
  • Half of the items in the "CLI reference" section have their short descriptions next to the command and the other half don't. IMO it's clearer if we just have the commands without descriptions in the list, but is it possible to make subheadings for the different subcommands (such as VM/Kernel/Image commands)?
  • Some of the changelogs don't render their links correctly, might also be a mistake on our side

In the CLI reference, is this (50% of commands with descriptions) the result of make tidy, or have you modified them by hand?

@dholbach
Copy link
Contributor Author

dholbach commented Jul 31, 2019 •
edited
Loading

This is defintely the right direction, it looks good! tada
A couple of things I noticed when running the docs locally:

* Videos (e.g. in "How to use Ignite to run VMs") have their link visible next to the thumbnail, it might be good to just have the thumbnail as the chapters above each video explain them

Ok, will add as a TODO item.

* Half of the items in the "CLI reference" section have their short descriptions next to the command and the other half don't. IMO it's clearer if we just have the commands without descriptions in the list, but is it possible to make subheadings for the different subcommands (such as VM/Kernel/Image commands)?

I used the descriptions that are currently listed under https://github.com/weaveworks/ignite/blob/master/docs/cli/ignite.md#see-also

As you can see in https://github.com/weaveworks/ignite/pull/246/files#diff-87b56d02ca5719fe568e2c07fffda67aR74 the titles will now we automatically generated from the document headings. I used a glob (*) to pull in the ones that currently are not listed (that was just an idea).

* Some of the changelogs don't render their links correctly, might also be a mistake on our side

Well spotted. Looks like "bare URLs" are not working - adding to TODO as well.

In the CLI refrence, is this (50% of commands with descriptions) the result of make tidy, or have you modified them by hand?

Ah yes, I wasn't quite sure that some of these bits are generated. I guess I need help here?

@dholbach
Copy link
Contributor Author

@luxas @twelho With the rest I'm going to need help.

@luxas luxas self-assigned this Aug 1, 2019
@luxas luxas added this to the v0.5.0 milestone Aug 1, 2019
luxas
luxas approved these changes Aug 1, 2019
View reviewed changes
Copy link
Contributor

@luxas luxas left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for getting this started @dholbach 💯 !
I've gone through this, checked it out, and fixed a couple of things e.g. support for both ignite, and ignited (#264), and added the api reference documentation.

register ignite on readthedocs and import

We can do this as a follow-up.

LGTM, I'm gonna go ahead and merge 👍
After this we can incrementally improve the docs.

@luxas luxas marked this pull request as ready for review August 1, 2019 11:54
@luxas luxas merged commit 57e29c9 into weaveworks:master Aug 1, 2019
@dholbach dholbach deleted the read-the-docs branch August 1, 2019 14:45
@luxas luxas removed the kind/enhancement Categorizes issue or PR as related to improving an existing feature. label Aug 6, 2019
@luxas luxas changed the title Start off read-the-docs effort for documentation Add a Read The Docs website: ignite.readthedocs.org Aug 6, 2019
@dholbach dholbach mentioned this pull request Sep 16, 2019
Merged
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@luxas luxas luxas approved these changes

Assignees

@luxas luxas

Labels
area/UX Let's make Ignite's UX great! kind/documentation Categorizes issue or PR as related to documentation. priority/important-longterm Important over the long term, but may not be staffed and/or may need multiple releases to complete.
Projects
None yet
Milestone
v0.5.0
Development

Successfully merging this pull request may close these issues.

Create a website with documentation
3 participants
@dholbach @twelho @luxas