I am using Fedora 18 on Virtual Box on my Windows XP desktop to learn Django. After going through the .txt documentation files, I discovered these files were written using restructuredText. I've been spending the last day or so trying to figure out how to convert the files into something readable (HTML, Latex, PDF, etc.). First thing I did, was install docutils (from source - download page) and used rst2html.py to convert the files to HTML to be readable.
When I used this tool, I was getting the Unknown interpreted text role "doc", Unknown interpreted text role "ref", Unknown interpreted text role "term" errors, and more when opening the docs/intro/index.txt, docs/intro/install.txt and docs/intro/tutorial01.txt files. I was able to find very little on Google describing the exact problem I was having so I tried to use a different option.
Naively thinking the errors were native to docutils I decided to search for another tool and found this page and installed restview. Well, I didn't realize restview used docutils so I ended up back at square one.
How do I get rid of these and other errors? Did I install docutils and restview correctly?
Please tell me if I need to add more info
You need to use Sphinx. This tool is used by the Django project and it defines additional reStructuredText constructs to complement those defined by docutils. Such as
http://sphinx-doc.org/markup/inline.html#role-doc
http://sphinx-doc.org/markup/inline.html#role-ref
http://sphinx-doc.org/markup/inline.html#role-term
Related
The pylzma library is a requirement for another tool that I would like to use. I am new to python and programming and have a few questions:
I have already followed the procedure to download and install pylzma from the following site since it seems to be the easiest:
https://code.google.com/p/threadzip/wiki/InstallingPylzma
But I get stuck at the byte compile py7zlib part.
How do I byte compile py7zlib?
When I check the documentation on the authors page http://www.joachim-bauch.de/projects/pylzma/ and go to the designated folder I see the following files:
In the /tmp/pylzma-0.4.6/build/lib.linux-i686-2.7 folder I see:
py7lib.py py7zlib.pyc pylzma.so
But no the "py7zlib.pwd" as stated on the authors page however I do see the "py7zlib.pyc" as stated on the original page listed.
Do I still need to compile this bytecode?
When I "import py7lib" in at the python prompt I see nothing, no feedback or error.
How do I check to see if this has been correctly imported and that I have installed this library correctly?
Thank you for your feedback.
We are using an environment variable to specify a path to a library we use. Most of the time it points to the released version but sometimes to a development version.
Anyway, it works ok when I use $(MyLib)/path;%(AdditionalIncludeDirectories) for building the C++ application but I can not open the project resources. However, when I use %(MyLib)/path;%(AdditionalIncludeDirectories) it works.
Now, what is the difference?
I thought the correct way is to use $(EnvVar) but for the resource editor it doesn't seems to work. And if $(EnvVar) is the correct way then why does Visual Studio use %(AdditionalIncludeDirectories) and not $(AdditionalIncludeDirectories)
The error I get is: fatal error RC1015: cannot open include file 'afxres.h'.
You use %(item) to refer to an MSBuild metadata item. Using $(AdditionalIncludeDirectories) would not work well if you also had an environment variable by that name. So %(MyLib)/path ought to resolve to just /path.
You can put echo %(MyLib)/path in a prebuild event to verify this.
Which is probably enough to stop confusing rc.exe, the resource compiler. Which is a stone-cold-old SDK utility, going back all the way to Windows version 1.0. It is pretty temperamental, very picky about command line options and .rc script file text encoding. Do keep in mind that it dates from an era long before Windows started to support a forward slash as a path separator, everybody had to use a backslash back in 1986.
So use "$(MyLib)\path" instead, including the double quotes so you don't confuzzle it when MyLib contains embedded spaces. And do favor using a project property sheet instead so there are some odds that somebody can still figure out how to get the project built correctly 2+ years from now.
There have been a couple of threads on this topic in the past that claim Sphinx doesn't support this at all. I had my doubts but either it has been updated since or the documentation for it was quite well hidden, because here is a link on the website stating otherwise:
http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cpp-domain
Anyway, I'm new to Sphinx but am trying to use it to (eventually) automate documentation using some text from some source C++ code. So far I haven't been able to get anywhere when using the sphinx-apidoc -o ... command. An almost blank document is created. I'm probably not using the right directives, since I don't know how - the supporting documentation hasn't been able to help me.
Can anyone provide some assistance with the basic steps needed to get it working? If it is not possible to auto-generate documentation from C++, what are the C++ domains for and how to use them?
On auto-generating C++ documentation:
After reading up on how to use sphinx at all, you should have a look into breathe:
Breathe provides a bridge between the Sphinx and Doxygen documentation
systems.
It is an easy way to include Doxygen information in a set of
documentation generated by Sphinx. The aim is to produce an autodoc
like support for people who enjoy using Sphinx but work with languages
other than Python. The system relies on the Doxygen’s xml output.
So additionally, you'll need to follow Doxygen commenting style and even setup an doxygen project. But I tried that and it works really well after the initial setup took place. Here is an excerpt of our CMakeLists.txt which might give you an idea on how sphinx and doxygen work together:
macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
add_custom_target(${TARGET_NAME}
COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
WORKING_DIRECTORY docs
DEPENDS doxygen
COMMENT ${COMMENT_STR}
)
endmacro(add_sphinx_target)
add_custom_target(doxygen
COMMAND doxygen docs/doxygen.conf
COMMENT "Build doxygen xml files used by sphinx/breathe."
)
add_sphinx_target(docs-html
html
"Build html documentation"
)
So after initial setup, essentially it boils down to:
build doxygen documentation with doxygen path/to/config
cd into the directory where the sphinx configuration is.
build sphinx documentation with sphinx-build . path/to/output
On the c++ domain:
Sphinx is a „little bit“ more than a system to auto-generate documentation. I would suggest you have a look at the examples (and consider that the sphinx website itself is written in sphinx reST code). Especially click the Show Source link on many sphinx-generated pages.
So if you cannot generate documentation automatically for a project, you have to do it yourself. Basically sphinx is a reST to whatever (LaTeX, HTML, …) compiler. So you can write arbitrary text, but the advantage is that it has a lot of commands for documenting source code of different languages. Each language gets its own domain (prefix or namespace) to separate the namespaces of the different languages. So for example I can document a python function using:
.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
Does something nasty with timers in repetition
(source)
I can do the same using the cpp domain:
.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
Describes a method with parameters and types.
(source)
So if you want to document your c++ project without doxygen+breathe but with sphinx, you'll have to write the restructured text files yourself. This also means that you split the documentation from your source code, which can be undesirable.
I hope that clears things up a bit. For further reading I strongly suggest that you have a good read on the sphinx tutorial and documentation until you understood what it actually does.
I need to add http://us3.php.net/xsl this module to my PHP but I'm really confused how I actually do this? It says in install from that link 'PHP 5 includes the XSL extension by default and can be enabled by adding the argument --with-xsl[=DIR] to your configure line. DIR is the libxslt installation directory.' But unsure where these files would be? I have a VPS and access to WHM Cpanel, can I do this from there? I came across the software and install module bit in WHM but get the feeling that's not what I want...
Go to WHM -> Software -> EasyApache (Apache Update)
On the EasyApache page, choose Start customizing based on profile now, and after a couple screens, choose Exhaustive Options List. Select the modules you want to install, XSL in your case, and proceed to recompile.
You need to compile PHP manually, if you want any modules that you don't currently have. There are plenty of tutorials how to do it, for example if you have Apache 2 as a webserver, then follow this page on php.net: http://www.php.net/manual/en/install.unix.apache2.php
When you compile PHP, one of the commands to do is
./configure
in which you can (and most webhostings do) supply many many arguments, which say which modules you want to have installed and what features PHP can use. It may look like this:
./configure '--prefix=/usr/local/php' '--with-config-file-path=/usr/local/php/lib' '--with-apxs' '--with-iconv=/usr/local/php' '--with-openssl=/usr' '--with-zlib=/usr' '--with-mysql' '--with-pgsql=/Users/marc/cvs/entropy-php4/php-module/build/postgresql-build' '--enable-cgi' '--with-gd' '--with-png-dir=/usr/local/php' '--with-freetype-dir=/usr/local/php' '--with-t1lib=/usr/local/php' '--with-jpeg-dir=/usr/local/php' '--with-tiff-dir=/usr/local/php' '--with-curl=/usr/local/php' '--with-mcal=/usr/local/php' '--with-mcrypt=/usr/local/php' '--with-mhash=/usr/local/php' '--with-pdflib=/usr/local/php' '--with-imap=../imap-2002d' '--with-imap-ssl=/usr' '--with-expat-dir=/usr/local/php' '--with-gettext=/usr/local/php' '--with-dom=/usr/local/php' '--with-dom-xslt=/usr/local/php' '--with-dom-exslt=/usr/local/php' '--with-xslt-sablot=/usr/local/php' '--with-mime-magic=/usr/local/php/etc/magic.mime' '--with-mssql=/usr/local/php' '--with-fbsql=/Users/marc/cvs/entropy-php4/php-module/build/frontbase-build/Library/FrontBase' '--with-ming=/Users/marc/cvs/entropy-php4/php-module/build/ming-build' '--enable-xslt' '--with-ldap' '--with-xml' '--with-xmlrpc' '--with-iodbc=/usr' '--enable-sockets' '--enable-dbx' '--enable-dbase' '--enable-trans-sid' '--enable-exif' '--enable-wddx' '--enable-ftp' '--enable-mbstring'
it this example there are a lot of enabled modules. You can also see what "configure line" was used to compile your current version of PHP in phpinfo (it's right at the top, third line).
Apparently it's XML-like. Example templates can be found in the gnome Anjuta shares on an Ubuntu install at /usr/share/anjuta/project/
I think I'll go back to Eclipse and gedit if it doesn't look like Anjuta has documented a decent auto-completion, project build, and syntax-highlighting template format. Others with the same question went fishing on Ubuntu forums and had no luck.
The answer might also help people trying to build automake scripts for svn repos at [https://stackoverflow.com/questions/5926366/using-anjuta-with-svn-how-to-create-the-project]
A bit overdue, but I found the official documentation, and remembered having seen your post. From the docs:
The template files look like xml documents and have normally the
extension .wiz. All templates and others related files are installed
by default in $anjuta_install_dir/share/anjuta/templates. But the
project wizard looks for templates in the sub directory
anjuta/templates of all user data directories as defined by XDG Base
Directory Specification too. It is possible to override a Anjuta
project template by an user one put, by example, in
~/.local/share/anjuta/templates.
The template file is divided in four parts: an header block, one or
more page blocks, a content block and an optional action block. The
file is read several times, one time for each block but before reading
it, the whole file go though a transformation pass and only the
resulting file must be a valid xml file. The transformation pass uses
autogen.