i'm working on a Mac and use Sphinx 1.6.3 to build a documentation for my software.
Recently I tried the Internationalization feature, which works quite well.
But now I wanted to export the different language into different folders:
doc/de
doc/en
doc/fr
According to the docs, its simple:
$ sphinx-build -b html sourcedir builddir
http://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build
So I tried this:
make -e SPHINXOPTS="-D language='en'" -b html /Applications/MAMP/htdocs/sakkadentrainer/doc/ /Applications/MAMP/htdocs/sakkadentrainer/doc/_build/html/en/
Which gives gives me the strange error:
Error: source directory and destination directory are same.
What am I doing wrong?
Issue solved. I had to use sphinx-build and not make
sphinx-build -b html /Applications/MAMP/htdocs/sakkadentrainer/doc/ /Applications/MAMP/htdocs/sakkadentrainer/doc_en/
Related
Background
I have some docs which include some download files. See example:
Make sure to download :download:`this file</foo/bar_v1.2.tar>` for more details
The site/downloads/foo/bar.tar file is created and moved into the directory as part of the build process.
I am using the sphinx-build -M html . site -W to build the docs.
My issue
When we change the version of the file, the file name changes. Sometimes folks can forget to update this place in the docs and rename the download file correctly.
When I run the sphinx-build command, I see the following error:
download file not readable: /path/to/site/downloads/foo/bar_v1.2.tar
... but the build process continues and sphinx-build exits 0.
My question
I would like sphinx-build to error out when it encounters an unreadable file, but I cannot figure out how to do this.
As noted above, I have tried the -W which is supposed to turn warnings into errors, but it does not work.
Other possibilities
My question stated that I think my problem will be solved by causing sphinx-build to fail for download file not readable messages, but if anyone else has solved similar issues in another way, I would love to hear about it
Thanks.
I'm not really experienced with graphics programming, but I got curious. I installed both libgtk-3-dev and gtk-3-examples on my Debian 10.7 machine. From there I listed the example package files using dpkg-query -L gtk-3-examples to find some example programs.
In the examples directory I found the following README file:
== Building the examples ==
The examples in this directory are built alongside the rest of GTK+.
The examples under the `application[1-10]` directories are also included in
the GTK+ API reference documentation, and can be built independently, using
the system libraries, by doing:
$ cd application1
$ make -f Makefile.example
Looks straight forward. However, following the directions exactly yields the following result:
make: Makefile.example: No such file or directory
make: *** No rule to make target 'Makefile.example'. Stop.
There are no "Makefile.example" files in the application folders. Running find -name "Makefile*" in the examples directory yields:
./application7/Makefile.in.gz
./application7/Makefile.am
./Makefile.in.gz
./application5/Makefile.in.gz
./application5/Makefile.am
./bp/Makefile.in.gz
./bp/Makefile.am
./application9/Makefile.in.gz
./application9/Makefile.am
./application6/Makefile.in.gz
./application6/Makefile.am
./application2/Makefile.in.gz
./application2/Makefile.am
./application10/Makefile.in.gz
./application10/Makefile.am
./application3/Makefile.in.gz
./application3/Makefile.am
./application1/Makefile.in.gz
./application1/Makefile.am
./application8/Makefile.in.gz
./application8/Makefile.am
./application4/Makefile.in.gz
./application4/Makefile.am
./Makefile.am
I've not had any luck building an example program using the above files. I'm guessing it is because of my unfamiliarity with auto tools? Is there an easy way to build an example GTK program using the above files or do I need know a lot more about make/autotools/configure to get a working example running?
Update:
The cant-run-makefile-am-what-should-i-do post is informative but does not provide a course of action when no configure, bootstrap, or autogen programs can be found within the package. The following command yields no results when executed in my examples directory: find -type f | grep -i -E "*conf*|*auto*|*boot*". I need one of those files to be provided in order to have a successful build (as far as I understand it anyway).
Sorry for the fuss! I'm used to installing regular packages and missed that I needed to download the full source code to get the examples working. So, originally I mentioned that I installed both libgtk-3-dev and gtk-3-examples. I did so using apt-get install libgtk-3-dev && apt-get install gtk-3-examples.
However, to build GTK along with its examples locally it looks like what you want to do is get the source package archive with apt-get source gtk-3-examples (or similar.. I think it actually picked a different meta-package for me when I ran that command).
Then, in my new gtk+3.0-3.24.5 directory there's a nice configure binary that I can run (with subsequent make and make install commands) which produce many files including example program binaries.
So with ./gtk+3.0-3.24.5/examples/application1/exampleapp I get a running example. Voila!
When I run Sphinx on my machine it installs for example
developers/integration.rst into developers/integration.html
but on readthedocs it installs it in
developers/integration/index.html
This makes the use of relative links in any raw commands fail.
Is there a way to force my machine install to use the same directory structure as readthedocs? Or other solutions?
That's basically the difference between the Standalone HTML Builder and the Directory HTML Builder. You can change the builder with the sphinx-builder option of the read-the-doc configuration file, or change your build option on the command line by specifying it with -b.
I hit this error message while trying to build gnote using GNU Autotools.
I had first run:
$ git clean -xf # to clean the tree of untracked files, then
$ autoreconf # to create the script named `configure`, and finally
$ ./configure # to check my system, and create Makefiles from their templates
Neither po/Makefile.in.in nor po/Makefile.in exist in the source tree that I downloaded.
Yet configure needs to make this po/Makefile, as called for in the root Makefile.am in this line:
SUBDIRS = data src po help
Where do I get, or how do I make, po/Makefile.in.in?
Like all Gnome related packages, gnote uses many steps of buildsystem setup beyond just running autoreconf.
The autogen.sh script gnote comes with should run all the required steps to set up the buildsystem.
As usual, run the autogen.sh script with the --help parameter if you want to call configure separately.
po/Makefile.in.in is created by running intltoolize from the intltool package. It needs to be run from the project tree's root directory.
There isn't much documentation on intltoolize that I could find except for the brief man page, but it's source code says that that it's a fork of an older utility called libtoolize, and it's a relatively short script.
(BTW, if you don't already have intltoolize installed, you can figure out which package installs it, with this: sudo apt-file find intltoolize.)
*.in files are templates used by AutoMake to create a Makefile.
.in.in is a soft link to /usr/share/intltool/Makefile.in.in.
I am using Sphinx to create documentation for my Python project in Windows. I need to generate PDF documentation. I found many explanation how to do this in Linux, but no good explanation how to do this in Windows. As far as i understand I need to create Latex format with Sphinx, and than use Texworks to convert Latex to PDF. Can someone provide step by step explanation how can I do this, assuming I created documentation in Latex format and installed Texworks?
Install MiKTeX (< 200mb)
wget -nv -N http://mirrors.ctan.org/systems/win32/miktex/setup/miktex-portable-2.9.4757.exe
7z.exe x -y miktex-portable-2.9.4757.exe -o"miktex"
Add the bin directory to your path
SET Path=%Path%;%CD%\miktex\miktex\bin
Run Sphinx's "make.bat" to generate the .tex file.
SET SPHINXOPTS=-W -E
make.bat latex
Invoke MiKTeX's pdflatex:
cd build/latex
pdflatex.exe YOUR_PROJECT_NAME.tex
The resultant PDF will be in your build/latex directory
Install the full tex live distribution, it will install latex, PDF backends and texworks. Yes it is much, yes, it will dl and install for a fat hour depending on your pipe. But it will be sub gig total, and harddisks are large nowadays.
From what I see, Texworks is just a simple LaTeX editor with some build functionality and latex syntax highlighting. It is not really needed for just compiling (you could use notepad)
Then it should be a matter of simply putting the tex live binary directory i the path and doing
pdflatex <yourlatexdocument.tex>
on the cmdline, at least that is what I do with the latex output of our own documentation generating tool
As you have figured out: use Sphinx to generate LaTeX source, and then run it through a LaTex compiler to produce your PDF.
Instead of troubling yourself with installing LaTeX (which can be daunting) and getting an editor set up, I suggest that you use one of the on-line LaTeX services. You then only have to create a project in ShareLaTeX or Overleaf, for example (which are in the process of merging), upload the contents of the Sphinx build\latex directory, compile on-line, and download the finished PDF.
This works reasonably well, but since the output targets are very different (HTML vs a formal document), you may have to fiddle with the reST to get things the way you like it.