Re: [PATCH 0/3] docs: User oriented documentation

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 20/03/2019 16:49, George Dunlap wrote:
> On 3/20/19 12:02 PM, Wei Liu wrote:
>> On Wed, Mar 20, 2019 at 11:35:10AM +0000, Andrew Cooper wrote:
>>> On 20/03/2019 11:28, Wei Liu wrote:
>>>> On Wed, Mar 20, 2019 at 11:23:57AM +0000, Andrew Cooper wrote:
>>>>> On 20/03/2019 11:20, Wei Liu wrote:
>>>>>> On Tue, Mar 19, 2019 at 04:20:04PM +0000, Andrew Cooper wrote:
>>>>>>> This is a project I've been musing over for a long time now, to try and
>>>>>>> address Xen's almost complete absense of documentation.
>>>>>>>
>>>>>>> This series, plus some other in-progress conversion of the command line doc,
>>>>>>> is available to view at:
>>>>>>>
>>>>>>>   https://andrewcoop-xen.readthedocs.io/en/latest/
>>>>>>>
>>>>>>> This is read-the-docs's automatic CI build of documentation from a branch on
>>>>>>> gitlab.  Observe that the docs don't look like they are out of the 90's, and
>>>>>>> are automatically translated into PDF and ePUB format as well.
>>>>>>>
>>>>>>> In due course I'll see about updating xenbits.xen.org/docs to render this as
>>>>>>> well, but I don't have sufficient tuits at the moment.
>>>>>>>
>>>>>>> Andrew Cooper (3):
>>>>>>>   docs/sphinx: Skeleton setup
>>>>>>>   docs/rst: Use pandoc to render ReStructuredText
>>>>>>>   docs/admin-guide: Boot time microcode loading
>>>>>> I don't think these changes introduce new dependencies in the build.
>>>>>> Assuming my observation is correct:
>>>>>>
>>>>>> Acked-by: Wei Liu <wei.liu2@citrix.com>
>>>>> In the short term, no.  In due course, we'll need virtualenv and a bit
>>>>> more integration for anyone wanting to build the sphinx tree locally,
>>>>> but I'm fairly sure we get virtualenv automatically by already having
>>>>> python as a build dependency.
>>>> I don't think python depends on virtualenv -- it's the other way around
>>>> on Debian.
>>>>
>>>> Using virtualenv can isolate build from host python, but that's it.  I
>>>> don't think virtualenv is a hard dependency . Distros already package
>>>> sphinx.
>>> The point of using virtualenv is to get a known-compatible set of
>>> dependencies.  See docs/sphinx/requirements.txt in patch 1.
>>>
>>> Use of the distro-packaged versions of sphinx/rtd-theme/docutils may
>>> work, but can be very hit-and-miss.
>> They can be fixed in due course.
>>
>> In any case, I don't think virtualenv is a hard requirement -- I was
>> thinking more along the line of developer / packager workflow. I think
>> it would be beneficial to have this series in tree, so people can
>> join the effort.
>>
>> What to do on xenbits is another matter.
> It seems like setting up a suitable sphinx environment should be done by
> the user (perhaps with some pointers).  Our make system shouldn't be
> creating its own virtual environment.  Having some scripts in
> automation/ would be useful, but it should be separate from the main doc
> build.

This patch series very deliberately doesn't set up a virtualenv,
(because doing that automatically is not something I'm happy with Xen's
makefiles doing) but does have minimal instructions beside the build
target and one file committed into the tree to allow users to do it
easily.  See patch 1.

~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel