I am using asciidoc with asciidoctor to create documentation for a current project.
I notice there is a markup to include files in the documentation like so:
link:index.html
or
link:protocol.json[Open the JSON file]
Is it possible to include a docx file as a link so that it would open externally or be able to downloaded?
Also can I put this file in a folder inside my asciidoc directory (for the sake of organization) and still be able to properly reference it?
You write something like this:
Open this link:somefile.docx[Word file] should work.
Or this link:file:///C:/Users/xxx/docs/otherfile.docx[second file].
It works with relative path or absolute path.
You need to ensure that the path to your file will be correct for the reader of your document.
Example: if you put the HTML files produced by Asciidoctor on a webserver (public or intranet), having a path referencing your local C: is not a good idea.
It is hard to tell you what to do without knowledge of your publication/distribution toolchain.
Related
I'm building a documentation for a platform that includes modules. I would like to let the documentations live in these modules repositories and include them in the "master" doc with the include command.
I tried the following :
.. include:: https://github.com/12rambau/sepal_ui_template/blob/master/doc/en.rst
But nothing was added to the file
Is it possible to use absolute link in includecommand ?
My main objective is not to use the include command but to avoid code ducplication and use a file that is available on the web. based on #Steve piercy answer I came up with this solution :
In the conf.py file I copy the content of the file from github
be careful and use the raw.githubusercontent.com link to avoid importing html
# [...]
# -- Copy the modules documentation ------------------------------------------
from urllib.request import urlretrieve
urlretrieve (
"https://raw.githubusercontent.com/12rambau/sepal_ui_template/master/doc/en.rst",
"modules/sepal_ui_template.rst"
)
after that the file is created under modules/sepal_ui_template.rst in my documentation and I can safely access it.
It will be download again every time I rebuild my documentation.
No. A fully qualified URL is not relative to the document. According to the docs for the include directive:
The directive argument is the path to the file to be included, relative to the document containing the directive.
There are alternatives, including this one.
Facebook's Pysa tool looks useful, in the Pysa tutorial exercises they refer to files that are provided in the pyre-check repository using a relative path to include a path outside of the exercise directory.
https://github.com/facebook/pyre-check/blob/master/pysa_tutorial/exercise1/.pyre_configuration
{
"source_directories": ["."],
"taint_models_path": ["."],
"search_path": [
"../../stubs/"
],
"exclude": [
".*/integration_test/.*"
]
}
There are stubs provided for Django in the pyre-check repository which if I know the path where pyre check is installed I can hard-code in my .pyre_configuration and get something working but another developer may install pyre-check differently.
Is there a better way to refer to these provided stubs or should I copy them to the repository I'm working on?
Many projects have a standard development environment, allowing for hard coded paths in the .pyre_configuration file. These will usually point into the venv, or some other standard install location for dependencies.
For projects without a standard development environment, you could trying incorporating pyre init into your setup scripts. pyre init will setup a fresh .pyre_configuration file with paths that correspond to the current install of pyre. For additional configuration you want to add on top of the generated .pyre_configuration file (such as a pointer to local taint models), you can hand write a .pyre_configuration.local, which will act as an overlay and overwrite/add to the content of .pyre_configuration.
Pyre-check looks for the stubs in the directory specified by the typeshed directive in the configuration file.
The easiest way is to move stubs provided for Django in the pyre-check repository to the typeshed directory that is in the pyre-check directory.
For example, if you have installed pyre-check to the ~/.local/lib directory, move the django directory from ~/.local/lib/pyre_check/stubs to ~/.local/lib/pyre_check/typeshed/third_party/2and3/ and make sure your .pyre_configuration file will look like this:
{
"source_directories": ["~/myproject"],
"taint_models_path": "~/myproject/taint",
"typeshed": "~/.local/lib/pyre_check/typeshed"
}
In this case, your Django stubs directory will be ~/.local/lib/pyre_check/typeshed/third_parth/2and3/django
Pyre-check uses the following algorithm to traverse across the typeshed directory:
If it contains the third_party subdirectory, it uses a legacy method: enters just the two subdirectories: stdlib and third_party and there looks for any subdirectory except those with names starting with 2 but not 2and3, and looks for the modules in those subdirectories like 2and3, e.g. in third_party/2and3/
Otherwise, it enters the subdirectories stubs and stdlib, and looks for modules there, e.g. in stubs/, but not in stubs/2and3/.
That's why specifying multiple paths may be perplexing and confusing, and the easiest way is to setup the typeshed directory to ~/.local/lib/pyre_check/typeshed/ and move django to third_parth/2and3, so it will be ~/.local/lib/pyre_check/typeshed/third_parth/2and3/django.
Also don't forget to copy the .pysa files that you need to the taint_models_path directory. Don't set it up to the directory of the Pyre-check, create your own new directory and copy only those files that are relevant to you.
I can make asciidoc use the local directory for the stylesheet by using the full path:
:stylesheet: /this/complicated/path/my.css
But I want to make my document both self-contained and movable. Is there a way to specify that I want it to use the file my.css from the same directory where the .adoc file is located?
If you do not specify a path, the stylesheet is assumed to be in the same directory as the document:
:stylesheet: my.css
See: https://asciidoctor.org/docs/user-manual/#applying-a-theme
By using image directive, the images are searched either in the current directory or captured directly with an absolute path.
Is there any way to extend the search path with other directories?
Example
Environment setup
Location of the .rst file: project_path/sphinx/source/core/myrst.rst
Location of the .png file: project_path/doxygen/html/myimage.png
Current scenario
Referencing the .png file:
.. image::../../../doxygen/html/myimage.png
Desired scenario
Referencing the .png file:
.. image_or_any_other_directive::myimage.png
Is there any sphinx extension that provides this functionality?
I'm experimenting with Sphinx and ReadTheDocs (RTD) to compile my documentation on every GitHub push. Unfortunately, RTD found multiple doc/docs folders containing a conf.py file.
My repository uses git sub-modules to embed third party libraries. Some of them are also documented using Sphinx. I assume the biggest (long lasting documentation build) wins and overwrites all static HTML pages in the final RTD view.
How can I exclude or tell RTD to ignore the folders of these sub-modules:
lib/cocotb
lib/osvvm
lib/vunit
docs/source/_themes/sphinx_rtd_theme
My documentation is located here:
docs/source/conf.py
docs/source/index.rst
As far as I have found, RTD does support *.yml files, but there is no entry to define the documentation root folder.
Any ideas to solve my problem?
Inside conf.py, there is a list that looks like this
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
You can put the files you want to ignore inside it like
exclude_patterns = ["lib/cocotb", "lib/osvvm", "lib/vunit", "docs/_themes/sphinx_rtd_theme"]
Please note that here the pattern is relative to the source directory, you can put / at the beginning of each file pattern above to make this more clear.
The main documentation folder and its conf.py can be configured in the Advanced Settings tab in the per project settings.
Example value: documentation/conf.py