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 On 13 March 2017 at 19:58, Роман Мещеряков wrote:

Hello,

I managed to read documentation finally. I made a fork of Twisted repository using these commands:

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 to generate narrative HTML documentation:

(twisted-dev-env) pi@zyuzino11:~/ColourDreams/Twisted-dev $ cd docs (twisted-dev-env) pi@zyuzino11:~/ColourDreams/Twisted-dev/docs $ make html sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v1.5.3

Exception occurred: 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 (twisted-dev-env) pi@zyuzino11:~/ColourDreams/Twisted-dev/docs $

Please help me to resolve this error!

-- Kind regards, Roman Mescheryakov

03.03.2017, 15:25, "Jean-Paul Calderone" :

On Fri, Mar 3, 2017 at 2:57 AM, Роман Мещеряков < romanmescheryakov@yandex.ru> wrote:

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-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

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

On Mar 13, 2017, at 9:24 PM, Craig Rodrigues wrote:

On Mon, Mar 13, 2017 at 12:58 PM, Роман Мещеряков mailto:romanmescheryakov@yandex.ru> wrote:

Exception occurred: 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

On Mar 14, 2017, at 12:53 AM, Роман Мещеряков wrote:

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? The steps I performed just were: 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 The result was fail, if I understood correctly, due to this error:

Running setup.py bdist_wheel for cryptography: started Running setup.py bdist_wheel for cryptography: finished with status 'error' Complete output from command /home/pi/ColourDreams/Twisted-dev/build/narrativedocs/bin/python -u -c "import setuptools, tokenize;__file__='/tmp/pip-build-LEVwwA/cryptography/setup.py';f=getattr(tokenize, 'open', open)(__file__);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, __file__, 'exec'))" bdist_wheel -d /tmp/tmpTiRC7Rpip-wheel- --python-tag cp27: 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

On Mar 14, 2017, at 6:28 AM, Роман Мещеряков wrote:

I installed libffi-dev and libssl-dev Raspbian packages, and run "tox -e narrativedocs" again. Now the error was about missing "sphinx-build" executable. So I activated virtualenv where Sphinx was previously installed and again issued "tox -e narrativedocs". Now the output was:

(twisted-dev-env) pi@zyuzino11:~/ColourDreams/Twisted-dev $ tox -e narrativedocs 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

Exception occurred: 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 (twisted-dev-env) pi@zyuzino11:~/ColourDreams/Twisted-dev $

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

On Mar 15, 2017, at 8:28 AM, Роман Мещеряков wrote:

...

Are you running the latest `tox`? (tox --version == 2.6.0) Yes

...

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'.

...

Did you copy this development environment from another machine, or move it to a different folder? No

...

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

On Thursday, March 16, 2017, Роман Мещеряков javascript:_e(%7B%7D,'cvml','romanmescheryakov@yandex.ru');> wrote:

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 it. Of course, there are many newbie questions related to that:

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