[Starlingx-discuss] ERROR: unknown environment with tox -e when bulding doc locally

[Jones, Bruce E]

If run tox against your local doc tree, it generates all the html files for you and you can point your browser at them and see exactly how the files will render in production.  

        brucej

-----Original Message-----
From: Dominig ar Foll (Intel Open Source) [mailto:dominig.arfoll at fridu.net] 
Sent: Thursday, September 12, 2019 1:29 PM
To: starlingx-discuss at lists.starlingx.io
Subject: Re: [Starlingx-discuss] ERROR: unknown environment with tox -e when bulding doc locally

Sorry

but if we want to motivate people to write more documentation we need to find a simpler way.
To write docs we need to be able to at least check the display of a page before committing in a simple way.

If the environment is complex to reproduce and to debug, then we should have, at least, somewhere a web page creation service.
How reviewer will check that was is proposed is OK and looks fine ?

It's a serious issue that needs to be addressed with urgency.

Dominig

On 12/09/2019 21:48, Ildiko Vancsa wrote:
>
>> On 2019. Sep 12., at 21:36, Jeremy Stanley <fungi at yuggoth.org> wrote:
>>
>> On 2019-09-12 20:50:35 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote:
>> [...]
>>> Is there any simpler way to check how a page would look before 
>>> commiting it in  Gerrrit ?
>> [...]
>>
>> "Simpler" is a relative term. Since tox is being used here to 
>> abstract away building a dedicated Python virtual environment, 
>> installing documentation build dependencies and running Sphinx 
>> commands to convert reStructuredText markup into HTML content, you 
>> would basically need to perform the same steps yourself instead (make 
>> sure your current working directory is the top-level directory of the 
>> Git repository's worktree):
>>
>>    virtualenv -p python3 mydocs
>>
>>    mydocs/bin/pip install -c 
>> https://git.openstack.org/cgit/openstack/requirements/plain/upper-con
>> straints.txt -r doc/requirements.txt
>>
>>    mydocs/bin/sphinx-build -a -E -W -d doc/build/doctrees -b html 
>> doc/source doc/build/html
>>
>> The commands above were inferred from the tox.ini file in that 
>> project. Resulting content should appear in the doc/build/html 
>> directory. Of course, I fully expect you'll see virtualenv break 
>> there the same way it does when tox tries to call it, but it's worth 
>> a try. I'm unable to reproduce the error on my systems so it's tough 
>> to be certain.
> […]
>
> I usually run the tests in a virtual machine to avoid having anything going wrong with my laptop. I can confirm that on a fresh Ubuntu 16.04 after installing tox and cloning the StarlingX docs repo the ‘tox -e docs’ command works like a charm.
>
> Thanks,
> Ildikó
>
>
>
> _______________________________________________
> Starlingx-discuss mailing list
> Starlingx-discuss at lists.starlingx.io
> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss

--
Dominig ar Foll
Senior Software Architect
Intel Open Source Technology Centre


_______________________________________________
Starlingx-discuss mailing list
Starlingx-discuss at lists.starlingx.io
http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss