With this structure:
$ tree
.
├── Editors.rst
└── Tool_vim.rst
From Editor.rst file I want to do a link to the Tool_vim.rst file.
I get it with:
Follow install from :doc:`Tool_linux_install`
But on Tool_linux_install.rst I have a menu with .. contents:: and sections but I don't succeed to do a link to the vim chapter:
Follow install from :doc:`Tool_linux_install#vim`
But I get an error when compiling:
Tool_vim.rst:423: WARNING: unknown document: Tool_linux_install#vim
The :doc: role can be used to link to another document, but it does not support linking to a specific location within the document.
Instead, use the :ref: role to link to a target defined by a label. It is possible to generate labels automatically with the sphinx.ext.autosectionlabel extension.
See also https://github.com/sphinx-doc/sphinx/issues/6766.
Related
Lets suppose there is a web based documentation available at docs.project
Directory structure
/ - project root
/docs - documentation files in asciidoc format
index.adoc - documentation entry point
/public - public directory
generate.rb
Desirable workflow
I change documentation source in /docs directory.
I commit and push changes.
When pushing, the server runs ruby <project_root>/generate.rb command that rewrites the html presentation of the documentation.
index.adoc
= Documetation
Some text
[plantuml]
....
Client --> Server: Request
Server --> Client: Response
....
generate.rb
require 'asciidoctor'
require 'asciidoctor-diagram'
ROOT = File.dirname(__FILE__)
entry = ROOT + '/docs/index.adoc'
outdir = ROOT + '/public'
Asciidoctor.convert_file entry, to_dir: outdir, mkdirs: true
Problem
Current generate.rb script puts index.html file in public while images go to docs thus they are not available when you open docs.project in browser.
How to specify the images path?
You can use imagesdir
You could move all your images that are being used in your index.adoc into the public folder(since this is your output folder) and can set imagesdir document attribute like:
:imagesdir: ../public/
inside your index.adoc file. You could learn more about imagesdir here
Your problem should be that when using the Ruby API, the default safe mode is set to :secure, which should prevent access to files which reside outside of the parent directory of the source file. I am assuming to_dir is allowed to write the file, while plantuml goes through a different generation process (probably initially generates the image and then includes it, preventing access to the directory). In any case, you have two options.
Use unsafe mode with:
Asciidoctor.convert_file entry, to_dir: outdir, mkdirs: true, safe: :unsafe
It is probably not the best solution, use only if you are running it with controlled content (and no one can put something like include::/etc/passwd[] in the adoc source).
Change the base_dir with:
Asciidoctor.convert_file entry, base_dir: '.', to_dir: outdir, mkdirs: true
Which should work, assuming your directory structure looks like:
.
├── docs
│ └── index.adoc
├── generate.rb
└── public
I was trying to serve a specific local go file as a documentation web page, but was not able to do it.
The official godoc documentation says:
With the -http flag (i.e. the godoc command), it runs as a web server and presents the documentation as a web page.
user_me$ godoc -http=:6060
This does create something similar as the go page but it does not render the specific file that I want to render. So I tried to provide the name of the file I wanted:
user_me$ godoc -http=:6000 hello.go
However, it just replies with:
usage: godoc package [name ...]
godoc -http=:6060
-ex=false: show examples in command line mode
-goroot="/usr/local/go": Go root directory
-html=false: print HTML in command-line mode
-http="": HTTP service address (e.g., ':6060')
-httptest.serve="": if non-empty, httptest.NewServer serves on this address and blocks
-index=false: enable search index
-index_files="": glob pattern specifying index files;if not empty, the index is read from these files in sorted order
-index_throttle=0.75: index throttle value; 0.0 = no time allocated, 1.0 = full throttle
-links=true: link identifiers to their declarations
-maxresults=10000: maximum number of full text search results shown
-notes="BUG": regular expression matching note markers to show
-play=false: enable playground in web interface
-q=false: arguments are considered search queries
-server="": webserver address for command line searches
-src=false: print (exported) source in command-line mode
-tabwidth=4: tab width
-templates="": directory containing alternate template files
-timestamps=false: show timestamps with directory listings
-url="": print HTML for named URL
-v=false: verbose mode
-write_index=false: write index to a file; the file name must be specified with -index_files
-zip="": zip file providing the file system to serve; disabled if empty
I also tried:
user_me$ godoc -url="localhost:8080" hello.go
but it didn't work.
I also tried:
godoc -server=localhost:8080 hello.go
but it replied with:
2014/07/01 10:45:56 open /usr/local/go/src/pkg/hello.go: no such file or directory
I even tried just generating the html thing itself:
godoc -html hello.go > hello.html
same error as above.
I also tried (since it was complaining that there was no file in the pkg dir):
godoc -html -goroo=$GOPATH hello.go > hello.html
At the end, I gave up. I don't know how this godoc thing works. I installed the hello.go program so that I there was something in the pkg file in the workspace. How do you generate a webpage with your documentation for your code?
godoc operates on package and type names, not filenames.
For example, to learn about io/ioutil package:
text output: godoc io/ioutil
just the ReadAll function: godoc io/ioutil ReadAll
in HTML: godoc -html io/ioutil ReadAll
in the browser:
godoc -http=:6060
click Packages and navigate from there
or go directly to http://localhost:6060/pkg/io/ioutil#ReadAll
To view documentation for your own code, it has to be included in your GOPATH.
Suppose your GOPATH includes $HOME/go/src, and the file you are interested in is $HOME/go/src/hey/world/doc.go, you would run:
godoc hey/world
...or start godoc in HTTP mode and browse to http://localhost:6060/pkg/hey/world
By default, godoc looks at the packages it finds via $GOROOT and $GOPATH. So given that your package is in Go workspace i.e in GOPATH, you can run
godoc fmt
which prints out documentation for fmt package.
If you want to generate docs for your package foo which is in $GOPATH/src/github.com/abcd/foo location, you should run
godoc github.com/abcd/foo
With the -http flag, godoc runs as a web server and presents the documentation as a web page.
godoc -http=:6060
Now navigate to http://localhost:6060/pkg/github.com/abcd/foo in browser to find docs as web page.
The -play flag can be used to enable playground in web interface.
To show HTML doc generated for your own code
Step 1) At command line start up the document web server, that is:
C:\>godoc -http=:6060
Step 2) Open a browser and use an explicit url the folder your code is.
The URL structure comes from the folder names under your GOPATH.
For example:
If my GOPATH is c:\go and I have code in c:\go\src\myfolder\mysubfolder
The URL I would uses is http://localhost:6060/pkg/myfolder/mysubfolder and this would show an HTML page for the .go files in there
Also you can use URL http://localhost:6060/pkg/myfolder, which will have a link to mysubfolder
Notes:
I'm not sure how to see your local code at the the http://localhost:6060/pkg level, maybe you can't
It is possible to "specify additional paths" so I don't think it has to be the src folder, see https://blog.golang.org/godoc-documenting-go-code
Running godoc on its own worked for me, but was really slow because it
generates docs for every single package in the standard library, while I only
care about the local package that I am working on. To that end, if your package is in a folder called something, you can move
the folder so that it looks like this:
godoc/src/something
Then, go to the godoc folder, and run
godoc -goroot .
Then, browse to localhost:6060.
On linux, and assuming you have cd'd into the package of which you want to read the documentation.
if you are using go modules, you can run below command
godoc -http=:6060 & xdg-open http://localhost:6060/pkg/$(go list -m)
It uses the -m flag to get the package path even though the root module directory does not contain any .go file.
If you are not yet using modules, you can run,
godoc -http=:6060 & xdg-open http://localhost:6060/pkg/$(go list -f "{{.ImportPath}}")
Note that unlike -m this command will not work appropriately if there is no .go files into the directory.
Check the go list subcommand help at https://golang.org/pkg/cmd/go/internal/list/
I want to create a link that refers to a section defined in another file.
I have found a similar question on "Python-Sphinx: Link to Section in external File" and I noticed there is an extension called "intersphinx".
So I tried this extension, but it doesn't work (Probably my usage is wrong).
I have tried the following.
conf.py
extensions = ['sphinx.ext.todo', 'sphinx.ext.intersphinx']
...
intersphinx_mapping = {'myproject': ('../build/html', None)}
foo.rst
...
****************
Install Bar
****************
Please refer :ref:`Bar Installation Instruction<myproject:bar_installation>`
I want to create a link like 'Bar Installation Instruction' with above markup.
bar.rst
...
**************************
Installation Instruction
**************************
.. _bar_installation:
some text...
When I run make html, I get the following warning and the link is not created.
foo.rst: WARNING: undefined label: myproject:bar_installation (if the link has no caption the label must precede a section header)
Thanks in advance.
Looks like it's not able to find your mapping inventory file. The first part of the tuple serves as the base URL for your links while the second part is the path to the inventory file. I believe the auto downloading of the inventory files (when you pass None) only works with URIs and not file paths.
In this example, I can build the documentation locally, but it will link to http://example.com/docs/bar.html
'myproject': (
'http://example.com/docs/',
'../html/objects.inv'
)
I have troubles creating a document directory (html) using sphinx-build.
I tried
sphinx-build -b html source build
as well as
make html
but in both cases only the html-files search.html, index.html and genindex.html are generated. The file modindex.html is missing.
In the file conf.py I set
html_domain_indices = True
so I should have a modindex.html file. What am I doing wrong? I get no error message after building the html files. I'm using Sphinx 1.1.3 and Python 2.7 on Windows XP.
Short version
run sphinx-apidoc -o . mymodule
uncomment and modify conf.py. For this example, sys.path.insert(0, os.path.abspath('mymodule'))
re-run make html
Long answer
I can reproduce the issue with this sample module:
$cat mymodule/mymodule.py
def fn1():
'''First function'''
pass
def fn2():
'''Second function'''
pass
Running sphinx-quickstart produces the following tree:
$tree
.
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
├── mymodule
└── mymodule.py
$cat index.rst
.. sphinx example documentation master file, created by
sphinx-quickstart on Mon Mar 30 15:28:37 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
with default index.rst:
Welcome to sphinx example's documentation!
==========================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Running make html at this point produces no output in _build/html/py-modindex.html. This is because sphinx needs .rst files describing every module. Fortunately it's easy to produce using sphinx-apidoc -o . mymodule.
This gives two new files, of which only mymodule.rst is necessary to fix the modindex issue in the question.
$head *mod*rst
==> modules.rst <==
mymodule
========
.. toctree::
:maxdepth: 4
mymodule
==> mymodule.rst <==
mymodule module
===============
.. automodule:: mymodule
:members:
:undoc-members:
:show-inheritance:
Running make html at this point still won't work. But uncommenting and changing the line beginning with sys.path.insert in conf.py fixes things.
Mine is: sys.path.insert(0, os.path.abspath('mymodule'))
PS: to avoid an additional warning, add modules to the Contents: toctree in the index.rst file.
The following is what I did for my project.
1. Install sphinx
pip install -U sphinx
2. Install theme (I've chosen sphinx_rtd_theme. Pleaser replace it with your choice)
pip install sphinx sphinx_rtd_theme
3. Create a doc directory under your project file
mkdir docs
4. Get into that directory
cd docs
5. Run sphinx-quickstart command
sphinx-quickstart
6. Run the following ( if you've enabled autodoc shpinx extension)
sphinx-apidoc -o source/ ../<modules_folder>
where source is the source folder used by sphinx and modules_folder is the folder your project's .py files-modules are in.
7. You will be prompted to reply to the questions below (change the answers according to your needs)
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: project_name
> Author name(s): your_nme
> Project release []: 1.01
> Project language [en]: en
8. It should look like the following if successfully run:
Creating file ...<***modules_folder***>/docs/source/conf.py.
Creating file ...<***modules_folder***>/docs/source/index.rst.
Creating file ...<***modules_folder***>/docs/Makefile.
Creating file ...<***modules_folder***>/docs/make.bat.
Finished: An initial directory structure has been created.
9. Edit conf.py and make sure the following lines are not commented (#):
import os # line 13
import sys # line 14
Note: .. stands for one directory up from doc directory
<modules_folder> is the folder your project's .py files-modules are in
sys.path.insert(0, os.path.abspath('../<modules_folder>/')) # line 16
make sure the following line exists
extensions = ['sphinx.ext.autodoc'] # line 34
change the theme if you'd like
html_theme = 'sphinx_rtd_theme' # line 51
10. Run shpinx-apidoc command
sphinx-apidoc -o . ..
Note:
. >> is for current directory
..>> is for one level up directory, i.e., the <modules_folder> project directory
11. Run make html command
.\make clean
.\make HTML
or
make clean
make html
12. Open your newely built webpage starting with
<modules_folder>/docs/build/html/index.html
Old question, but "working on the hard drive but not on ReadTheDocs" often has an easy fix.
Go to readthedocs
Navigate to your "Project Home"
Click 'Admin' then 'Advanced Settings'
Find and check the box for 'Install Project'
Return to 'Overview'
Build a new version
Check if it worked
Come back here and thank me
configure scripts always include something like the following in the help message:
...
By default, `make install' will install all the files in
`/usr/local/bin', `/usr/local/lib' etc. You can specify
an installation prefix other than `/usr/local' using `--prefix',
for instance `--prefix=$HOME'.
For better control, use the options below.
Fine tuning of the installation directories:
--bindir=DIR user executables [EPREFIX/bin]
--sbindir=DIR system admin executables [EPREFIX/sbin]
--libexecdir=DIR program executables [EPREFIX/libexec]
--sysconfdir=DIR read-only single-machine data [PREFIX/etc]
--sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com]
--localstatedir=DIR modifiable single-machine data [PREFIX/var]
--libdir=DIR object code libraries [EPREFIX/lib]
--includedir=DIR C header files [PREFIX/include]
--oldincludedir=DIR C header files for non-gcc [/usr/include]
--datarootdir=DIR read-only arch.-independent data root [PREFIX/share]
--datadir=DIR read-only architecture-independent data [DATAROOTDIR]
--infodir=DIR info documentation [DATAROOTDIR/info]
--localedir=DIR locale-dependent data [DATAROOTDIR/locale]
--mandir=DIR man documentation [DATAROOTDIR/man]
--docdir=DIR documentation root
[DATAROOTDIR/doc/gedit-line-ending-style-plugin]
--htmldir=DIR html documentation [DOCDIR]
--dvidir=DIR dvi documentation [DOCDIR]
--pdfdir=DIR pdf documentation [DOCDIR]
--psdir=DIR ps documentation [DOCDIR]
Program names:
--program-prefix=PREFIX prepend PREFIX to installed program names
...
What I would like to do is add "plugindir", to this section, as in:
...
--dvidir=DIR dvi documentation [DOCDIR]
--pdfdir=DIR pdf documentation [DOCDIR]
--psdir=DIR ps documentation [DOCDIR]
--plugindir=DIR Gedit plugin files [LIBDIR/gedit-2/plugins]
...
so that users would be able to pass in --plugindir=... to the configure script.
How can I do this?
Put the following lines in configure.ac, near the beginning:
AC_ARG_WITH([pkgconfigdir],
[AS_HELP_STRING([--with-pkgconfigdir=DIR], [pkgconfig files])],
[pkgconfigdir=$withval],
[pkgconfigdir="\${libdir}/pkgconfig"])
AC_SUBST([pkgconfigdir], [$pkgconfigdir])
Then, in Makefile.am, you can refer to the directory like this:
pkgconfigdir = #pkgconfigdir#
pkgconfig_DATA = mylibrary.pc
If I'm correct those paths are set in the share/autoconf/autoconf/general.m4 file. The list is hardcoded so it is difficult to insert things in the list. You can add extra help information using the macro AS_HELP_STRING.
There are some examples that add a plugindir, for example in gstreamer, gimp, but those don't have a configurable plugin directory.
I think you are on the right track with AC_SUBST.
Additionally, I think you can modify or extend the --help output of configure with AS_HELP_STRING.
See: http://www.gnu.org/s/hello/manual/autoconf/Pretty-Help-Strings.html