On Fri, Nov 08, 2019 at 09:41:30AM +0100, Stefan Hajnoczi wrote: > On Thu, Nov 07, 2019 at 04:01:42PM +0000, Daniel P. Berrangé wrote: > > On Thu, Nov 07, 2019 at 04:44:34PM +0100, Stefan Hajnoczi wrote: > > > On Thu, Nov 7, 2019 at 11:07 AM Daniel P. Berrangé <berra...@redhat.com> > > > wrote: > > > > > > > > On Wed, Nov 06, 2019 at 05:19:28PM +0100, Stefan Hajnoczi wrote: > > > > > Hi, > > > > > You can now access the latest QEMU HTML documentation built from > > > > > qemu.git/master nightly at: > > > > > > > > > > https://wiki.qemu.org/docs/qemu-doc.html > > > > > https://wiki.qemu.org/docs/qemu-qmp-ref.html > > > > > https://wiki.qemu.org/docs/qemu-ga-ref.html > > > > > ...as well as interop/ and specs/ > > > > > > > > > > Feel free to link to the documentation from the QEMU website and/or > > > > > wiki! > > > > > > > > What's the reason for putting on wiki.qemu.org URL ? It feels like > > > > having it under www.qemu.org would be a more natural home, especially > > > > if we can then make it pick up the jekyll theme around the pages. > > > > > > > > Ideally we should publish the docs under versioned URL when we > > > > make a release. eg /docs/latest/.... for current GIT master > > > > which I presume the above is tracking, and then a /docs/$VERSION/... > > > > for each major release we cut. > > > > > > > > That way users can get an accurate view of features in the QEMU > > > > they are actually using. > > > > > > Versioned release docs should be generated during the release process. > > > I have CCed Mike Roth. That way the docs are available as soon as the > > > release drops. This container image only runs once a day and would > > > leave a window when users cannot access the docs yet. > > > > > > Moving from wiki.qemu.org should be possible. How does the jekyll > > > theme you mentioned work? > > > > IIUC, when there's a push to the qemu-web.git repo, some git hook (?) > > runs on the server which invokes jekyll to build the content, and > > then publish it to the webroot. > > > > To integrate these docs into that we need something along the lines > > of: > > > > 1. Generate the HTML files as you do now > > 2. Copy them into the qemu-web.git in a /docs/ subdir > > 3. Prepend a magic header to make jeykll process the file > > > > --- > > permalink: /docs/qemu-doc > > --- > > > > 4. Trigger the jekyll builder to refresh the generated docs > > 5. Publish the docs to the webroot > > > > You can see what I did here as an example where I simply committed > > the generated docs to qemu-web.git: > > > > https://www.mail-archive.com/qemu-devel@nongnu.org/msg578110.html > > > > If we're not storing the generated docs in git, then when > > pushing to qemu-web.git we need to ensure we preserve the > > extra /docs dir content in some manner. > > For qemu.git/master the built docs might change every day. Committing > them to qemu-web.git seems like overkill. I'll send a documentation.md > patch for qemu-web.git instead that simply links to > wiki.qemu.org/docs/.
Yeah, to be clear I wasn't suggesting committing them to qemu-web.git. Really we just need to put the generated .html files into some scratch directory on the web server where there qemu-web.git jekyll build can automatically find them & process them in the same way it does for content that is committed. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
