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

[George Dunlap <george.dunlap@xxxxxxxxxx>]

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

 -George

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