[Twisted-Python] Minor fixes in the “Customizing twistd logging” section

[Роман Мещеряков]

_______________________________________________
Twisted-Python mailing list
Twisted-***@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Team at TruBrain]

Dear Twisted general discussion, We would like to acknowledge that we have received your request and a ticket has been created. A support representative will be reviewing your request and will send you a personal response.(usually within 24 hours). To view the status of the ticket or add comments, please visit https://trubrain.freshdesk.com/helpdesk/tickets/264 Thank you for your patience. Sincerely, TruBrain Support Team

[Jean-Paul Calderone]

Hi everyone,
*On the documentation web page
https://twistedmatrix.com/documents/current/core/howto/application.html
<https://twistedmatrix.com/documents/current/core/howto/application.html>
in the “Customizing twistd logging” section there are 2 examples which as I
can see are a bit outdated in terms of imported module names and some other
minor details. I would like to fix that. Is this change is worth doing? If
so, please guide how can I do it. My GitHub login, if it’s needed, is
RomanMeR.*

Hi РПЌаМ,

Thanks for your interest in improving Twisted! Have a look at
https://twistedmatrix.com/trac/wiki/TwistedDevelopment and then let us know
if you have further questions.

Jean-Paul

[Роман Мещеряков]

_______________________________________________
Twisted-Python mailing list
Twisted-***@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[James Broadhead]

Hey there --

One way would be to use virtualenv to gather the dependencies without
installing them globally:

mkdir -p ~/venv
virtualenv ~/venv/twisted_docs # `sudo pip install virtualenv` first if
you don't have this command
source ~/venv/twisted_docs/bin/activate
pip install sphinx twisted
cd <repo>/docs
make html

James

Hello,
I managed to read documentation finally. I made a fork of Twisted
git clone https://github.com/<yourusername>/twisted.git Twisted
cd Twisted
git remote add upstream https://github.com/twisted/twisted.git
git fetch upstream
git branch -u upstream/trunk trunk
Then created python virtualenv and installed Sphinx into it. Then I tried
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.5.3
File "conf.py", line 45, in <module>
from twisted import version as twisted_version_object
ImportError: No module named twisted
The full traceback has been saved in /tmp/sphinx-err-75zxJ8.log, if you
want to report the issue to the developers.
Please also report this if it was a user error, so that a better error
message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-
doc/sphinx/issues>. Thanks!
Makefile:53: ПшОбка выпПлМеМОя рецепта Ўля целО «html»
make: *** [html] ОшОбка 1
Please help me to resolve this error!
--
Kind regards, Roman Mescheryakov
On Fri, Mar 3, 2017 at 2:57 AM, РПЌаМ МещерякПв <
Hi everyone,
*On the documentation web page
https://twistedmatrix.com/documents/current/core/howto/application.html
<https://twistedmatrix.com/documents/current/core/howto/application.html>
in the “Customizing twistd logging” section there are 2 examples which as I
can see are a bit outdated in terms of imported module names and some other
minor details. I would like to fix that. Is this change is worth doing? If
so, please guide how can I do it. My GitHub login, if it’s needed, is
RomanMeR.*
Hi РПЌаМ,
Thanks for your interest in improving Twisted! Have a look at
https://twistedmatrix.com/trac/wiki/TwistedDevelopment and then let us
know if you have further questions.
Jean-Paul
,
_______________________________________________
Twisted-Python mailing list
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
_______________________________________________
Twisted-Python mailing list
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Craig Rodrigues]

On Mon, Mar 13, 2017 at 12:58 PM, РПЌаМ МещерякПв <

File "conf.py", line 45, in <module>
from twisted import version as twisted_version_object
ImportError: No module named twisted

Looks like Twisted needs to be installed in order to build the docs.

I would suggest using a virtualenv for everything, and installing Twisted
from your checkout into it in it.


python -m virtualenv my_venv # Python 2

or

python3 -m venv my_venv # Python 3

source my_venv/bin/activate
#
git clone https://github.com/<yourusername>/twisted.git Twisted
cd Twisted
python setup.py develop # this installs Twisted in your virtual env
git remote add upstream https://github.com/twisted/twisted.git
git fetch upstream
git branch -u upstream/trunk trunk
#
pip install sphinx
cd docs
make html



--
Craig

[Glyph Lefkowitz]

File "conf.py", line 45, in <module>
from twisted import version as twisted_version_object
ImportError: No module named twisted
Looks like Twisted needs to be installed in order to build the docs.
I would suggest using a virtualenv for everything, and installing Twisted
from your checkout into it in it.

My suggestion would be to use the tox environments for this that we already provide :).

`tox -e apidocs` will build the API documentation, and `tox -e narrativedocs` will build the narrative documentation. This has the advantage that if we change the required packages for doc-building in the future, these commands will automatically re-build an appropriate virtualenv for the task.

To discover what environments are available, `tox -l`.

-glyph

[Роман Мещеряков]

_______________________________________________
Twisted-Python mailing list
Twisted-***@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Glyph Lefkowitz]

I decided to try Glyph's suggestion first.
By the way, I'm trying to compile twisted documentation on Raspbian, is this platform suitable for that?
sudo pip install tox (Glyph said I shouldn't install packages globally but it's too late for this Raspbian installation...)
Changed current directory to that where tox.ini resides
I didn't activate any virtual environments
tox -e narrativedocs
Running setup.py bdist_wheel for cryptography: started
Running setup.py bdist_wheel for cryptography: finished with status 'error'
Package libffi was not found in the pkg-config search path.
Perhaps you should add the directory containing `libffi.pc'
to the PKG_CONFIG_PATH environment variable
No package 'libffi' found
Maybe it's because Raspbian is not suitable for twisted development? If this is the case, can I use Windows?

Raspbian should be fine, but you do have to have enough dependencies installed. In this case you need to apt install libffi-dev and openssl-dev; it will be slow to build the first time (for each version of python) but it will speed up a lot after that due to build caching.

(Specifically this is because it is building Cryptography, which does not yet ship a manylinux1 wheel.)

Let me know if that works,

-g

[Роман Мещеряков]

_______________________________________________
Twisted-Python mailing list
Twisted-***@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Glyph Lefkowitz]

GLOB sdist-make: /home/pi/ColourDreams/Twisted-dev/setup.py
narrativedocs inst-nodeps: /home/pi/ColourDreams/Twisted-dev/build/dist/Twisted-17.1.0dev0.zip
narrativedocs installed: appdirs==1.4.3,asn1crypto==0.21.1,attrs==16.3.0,Automat==0.5.0,constantly==15.1.0,enum34==1.1.6,idna==2.5,incremental==16.10.1,ipaddress==1.0.18,packaging==16.8,pycparser==2.17,pyflakes==1.5.0,pyparsing==2.2.0,requests==2.13.0,six==1.10.0,Twisted==17.1.0.dev0,zope.interface==4.3.3
narrativedocs runtests: PYTHONHASHSEED='496434055'
narrativedocs runtests: commands[0] | python -c import sys; print(sys.prefix)
/home/pi/ColourDreams/Twisted-dev/build/narrativedocs
narrativedocs runtests: commands[1] | python -c import sys; print(sys.exec_prefix)
/home/pi/ColourDreams/Twisted-dev/build/narrativedocs
narrativedocs runtests: commands[2] | python -c import sys; print(sys.executable)
/home/pi/ColourDreams/Twisted-dev/build/narrativedocs/bin/python
narrativedocs runtests: commands[3] | python --version
Python 2.7.9
narrativedocs runtests: commands[4] | sphinx-build -aW -b html -d /home/pi/ColourDreams/Twisted-dev/docs/_build /home/pi/ColourDreams/Twisted-dev/docs /home/pi/ColourDreams/Twisted-dev/docs/_build/
WARNING:test command found but not installed in testenv
cmd: /home/pi/twisted-dev-env/bin/sphinx-build
env: /home/pi/ColourDreams/Twisted-dev/build/narrativedocs
Maybe you forgot to specify a dependency? See also the whitelist_externals envconfig setting.
Running Sphinx v1.5.3
File "conf.py", line 45, in <module>
ImportError: No module named twisted
The full traceback has been saved in /tmp/sphinx-err-s9PZVd.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
ERROR: InvocationError: '/home/pi/twisted-dev-env/bin/sphinx-build -aW -b html -d /home/pi/ColourDreams/Twisted-dev/docs/_build /home/pi/ColourDreams/Twisted-dev/docs /home/pi/ColourDreams/Twisted-dev/docs/_build/'
__________________________________________________________ summary __________________________________________________________
ERROR: narrativedocs: commands failed
The error is "twisted" module missing. How could I fix that? Should I install Twisted Python package to my virtualenv? Now I only have Twisted Python package installed globally.

From what I've seen here, it doesn't look like you've done anything wrong - this should work. So it's going to require some investigation.

I don't know why it would be choosing to 'inst-nodeps' when the deps clearly aren't installed yet. When I do this, what I see is:

GLOB sdist-make: /Users/glyph/Projects/Twisted/setup.py
narrativedocs create: /Users/glyph/Projects/Twisted/build/narrativedocs
narrativedocs inst: /Users/glyph/Projects/Twisted/build/dist/Twisted-17.1.0.dev0.zip
narrativedocs installed: alabaster==0.7.10,amptrac==0.1,appdirs==1.4.3,asn1crypto==0.21.1,astroid==1.4.9,attrs==16.3.0,Automat==0.5.0,Babel==2.3.4,cffi==1.9.1,colorama==0.3.7,constantly==15.1.0,cryptography==1.8.1,docutils==0.13.1,enum34==1.1.6,epydoc==3.0.1,extras==1.0.0,fixtures==3.0.0,idna==2.5,imagesize==0.7.1,incremental==16.10.1,ipaddress==1.0.18,Jinja2==2.9.5,lazy-object-proxy==1.2.2,linecache2==1.0.0,logilab-common==1.2.1,MarkupSafe==1.0,packaging==16.8,pbr==2.0.0,pyasn1==0.2.3,pyasn1-modules==0.0.8,pycodestyle==2.0.0,pycparser==2.17,pydoctor==16.3.0,pyflakes==1.5.0,Pygments==2.2.0,pylint==1.5.6,pyOpenSSL==16.2.0,pyparsing==2.2.0,python-mimeparse==1.6.0,python-subunit==1.2.0,pytz==2016.10,requests==2.13.0,service-identity==16.0.0,six==1.10.0,snowballstemmer==1.2.1,Sphinx==1.5.3,testtools==2.2.0,traceback2==1.4.0,treq==16.12.0,Twisted==17.1.0.dev0,twisted-dev-tools==0.0.2,twistedchecker==0.7.1,unittest2==1.1.0,wrapt==1.10.10,zope.interface==4.3.3
narrativedocs runtests: PYTHONHASHSEED='3320851011'
narrativedocs runtests: commands[0] | python -c import sys; print(sys.prefix)
/Users/glyph/Projects/Twisted/build/narrativedocs/bin/..
narrativedocs runtests: commands[1] | python -c import sys; print(sys.exec_prefix)
/Users/glyph/Projects/Twisted/build/narrativedocs/bin/..
narrativedocs runtests: commands[2] | python -c import sys; print(sys.executable)
/Users/glyph/Projects/Twisted/build/narrativedocs/bin/python
narrativedocs runtests: commands[3] | python --version
Python 2.7.12
narrativedocs runtests: commands[4] | sphinx-build -aW -b html -d /Users/glyph/Projects/Twisted/docs/_build /Users/glyph/Projects/Twisted/docs /Users/glyph/Projects/Twisted/docs/_build/
Running Sphinx v1.5.3
making output directory...
loading pickled environment... not yet created
loading intersphinx inventory from http://docs.python.org/3.3/objects.inv...
intersphinx inventory has moved: http://docs.python.org/3.3/objects.inv -> https://docs.python.org/3.3/objects.inv
loading intersphinx inventory from http://docs.python.org/2.7/objects.inv...
intersphinx inventory has moved: http://docs.python.org/2.7/objects.inv -> https://docs.python.org/2.7/objects.inv
building [mo]: all of 0 po files
building [html]: all source files
updating environment: 135 added, 0 changed, 0 removed
reading sources... [100%] words/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] words/index
generating indices... genindex
writing additional pages... search
copying images... [100%] web/howto/../img/web-process.png
copying downloadable files... [ 58%] core/howto/tutorial/listings/finger/twisted/plugins/finger_tutcopying downloadable files... [ 84%] core/howto/listings/systemd/www.example.com.socketactivated.secopying downloadable files... [100%] core/howto/tutorial/listings/finger/fingerPBclient.py
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
_____________________________________________ summary _____________________________________________
narrativedocs: commands succeeded
congratulations :)


So, a few questions for you:

Are you running the latest `tox`? (tox --version == 2.6.0)
This is not the first time you've run 'tox', or it would have the 'narrativedocs create' line above. Did you see what happened on the earlier runs? Did they all fail?
Can you try re-creating the virtual environment? Either `tox -r -e narrativedocs` or `rm -fr build/; tox -e narrativedocs`
Can you try doing this against a 'dev' install, i.e. `tox --develop -e narrativedocs`?
What happens if you make a new virtual environment and do `pip install .../path/to/twisted[dev]` (just .[dev] if you're in the twisted dir)? Specifically: does sphinx get installed in that virtual environment?
Did you copy this development environment from another machine, or move it to a different folder?

Hopefully we can get to the bottom of this and learn something for future contributors about whatever pitfall you've encountered!

Thanks for your patience,

-glyph

[Роман Мещеряков]

_______________________________________________
Twisted-Python mailing list
Twisted-***@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Glyph Lefkowitz]

Post by Glyph Lefkowitz
Are you running the latest `tox`? (tox --version == 2.6.0)

Yes

Post by Glyph Lefkowitz
This is not the first time you've run 'tox', or it would have the 'narrativedocs create' line above. Did you see what happened on the earlier runs? Did they all fail?

Yes, they all failed. I don't have tox output from previous runs. As I remember, the first 'tox -e narrativedocs' run failed because of missing libffi dependency, so this is possible first step one needs to reproduce the problem with running 'narrativedocs inst-nodeps' instead of 'narrativedocs create'.

Post by Glyph Lefkowitz
Did you copy this development environment from another machine, or move it to a different folder?

No

Post by Glyph Lefkowitz
Can you try re-creating the virtual environment? Either `tox -r -e narrativedocs` or `rm -fr build/; tox -e narrativedocs`

I tried the `tox -r -e narrativedocs` command and it succeeded! Docs built successfully.
Thank you Glyph for helping :) And thanks to all who responded as well! :)

You're welcome! Glad we got you up and running, sorry we couldn't figure out what the problem was.

One thing that is left unclear to me: the `narrativedocs installed` line in the tox output contains a long list of installed modules. Where were they installed? Because `pip list` doesn't show me them neither for the virtual environment which was active when I run tox nor for the global list.

`tox` is a tool which creates multiple virtualenvs for testing a project in multiple configurations, and for running multiple tasks associated with a project. (Like, for example, generating narrative documentation.)

Twisted is weird and puts its tox venvs in 'build/<envname>'; normally they're in '.tox/envname'. (see http://twistedmatrix.com/trac/ticket/9040). You can find your venv in build/narrativedocs.

-glyph

[Роман Мещеряков]

_______________________________________________
Twisted-Python mailing list
Twisted-***@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Craig Rodrigues]

OK, got it.
Back to the subject of this e-mail, I created ticket #9084
<https://twistedmatrix.com/trac/ticket/9084> and attached proposed fix to
1. Did I filled bug correctly?

I think the bug you filed is fine.

1. Is it right that I uploaded fix immediately to the just-created bug?

Instead of uploading the patch to Trac, it is preferred that you follow the
procedures here, even for a documentation patch.

http://twistedmatrix.com/trac/wiki/TwistedDevelopment#SubmittingaPatch

That includes all the steps for GitHub, Newsfile, setting the "review"
keyword on the Trac ticket, etc.

Thank you for your patience, and contributions to Twisted, especially for
the docs, which is important for new users

--
Craig

[Роман Мещеряков]

_______________________________________________
Twisted-Python mailing list
Twisted-***@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python