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

[Jeremy Stanley]

On 2019-09-12 22:29:04 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote:
> 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.
[...]

It's an environment optimized for embedding documentation in and
extracting documentation from software written in the Python
programming language. StarlingX borrowed its documentation workflow
from OpenStack, whose software is written almost entirely in Python
(the OpenStack community wanted to make sure that its developers
didn't have any excuse to avoid writing and updating documentation).
With this, of course, comes the complexity of getting a Python
software development environment going, which I can understand might
seem odd or challenging to folks who are not computer programmers,
or perhaps who focus on other languages are are disinterested in
getting acquainted with Python language ecosystem conventions and
norms).

Regardless of what tooling is used to manage documentation, I expect
that the basics of making it possible to write in a simple markup
language, being able to propose and review changes to documentation
prior to publication, and recording changes under annotated revision
control are still beneficial, as is the ability to take advantage of
continuous integration and deployment automation to reject proposed
changes for common errors or style deviations and to publish them
automatically on approval. The current solution meets those needs,
but they could still be met by using different documentation build
tooling too as long as someone writes Zuul jobs to install and run
that instead of python+tox+virtualenv+sphinx.
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20190912/b43c4293/attachment-0001.sig>