I'm new to sphinx and I need to pass a value from conf.py to my rst files. Is this possible from within sphinx?
My use case is the following: I want to include code snippets that are generated along with the documentation. The problem is that the files reside in a build directory, and I have no way of knowing the relative path between the source and build directory.
index.rst:
.. literalinclude:: |BUILD_DIR|/generated.txt
The conf.py is generated at compile time and contains the path to the build directory.
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.
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.
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
I'm attempting to write a Ruby script that will delete certain files from the Xcode project. I can find the files based on the absolute path and remove them from the project using the remove_from_project method of PBXFileReference. However this leaves source files (e.g. .m or .swift files) in the "Compile Sources" build phase of whatever target(s) it is a member of, but without a name.
I know I need to also remove the file from the target(s) but there seems to be no easy link between a PBXFileReference and a target (PBXNativeTarget).
From what I can make out I need to iterate through each of the project's targets, then iterate through the files or files_references of that target's source_build_phase looking for the PBXFileReference I already have.
Is this correct or am I missing some obvious link such e.g. file_ref.target_memberships?
if (object.is_a?(Xcodeproj::Project::Object::PBXFileReference))
if (!object.real_path.exist?)
object.remove_from_project
end
end
project.save(project_path)
Not sure when this was introduced, but as of xcodeproj version 1.15.0, you can can get the build files associated with a file reference with:
file_ref.build_files
From the documentation:
Method: Xcodeproj::Project::Object::PBXFileReference#build_files
#build_files ⇒ Array<PBXBuildFile>
Returns the build files associated with the current file reference.
Returns:
(Array<PBXBuildFile>) — the build files associated with the current file reference.
Seems like this should do the trick:
file_ref.build_files.each { |file| file.remove_from_project }
I have created a Sub project which just prints "Hello World". My goal is to create a C file inside the same subproject but within a folder named "src", also I want to create a H file within a folder named "include".
The H file contains only one function declaration "void printContent();" and the C file contains its definition which prints "Hello Buddy".
I added the C file inside the Source Files section of Sub project and added the H file inside the Header File Section, but when I compile the subproject and try to deploy it on to an emulator, I got an error.
BUILD: [01:0000000047:ERRORE] NMAKE : U1073: don't know how to make 'obj\ARMV4I\debug\content.obj'
I tried to configure the subproject by providing the below lines in the sources file of every Sub project.
INCLUDES= include/
But nothing changed and the problem still persists.
In wince subproject, sub folders are treated differently in the source file layout.
Rule No.1 You can't have both source and dirs files in the same folder.
So you either use one folder, or use several sub folders, then the root folder is clean and have one dirs file and several folders, no source file.
Rule No. 2 Each sub folder should have both source and makefile
You can copy and then edit the source file, the makefile will always be the same.
Ok, if you are going to use subfolder just to make the folder structure cleaner, my suggestion is that you create 2 subprojects, one is the main subproject; the other includes all your src files and its type is set to be static library. Then you can link to the static .lib file just as you are including them as in a subfolder. Of cource you need to set the additional include folder and input library.