We have a set of Ansible modules on GitHub (https://github.com/zhmcclient/zhmc-ansible-modules) and can generate HTML documentation from it using Sphinx. However, the build process includes a step where a documentationgenerator tool from Ansible is run to generate .rst files from the Python module source.
We have set up an RTD project for this (http://zhmc-ansible-modules.readthedocs.io/), but that extra step is not run there, of course.
-> How can we get that extra step run within the build process that runs on RTD?
RTD does not support intermediary steps in its build process. You must provide source files in your repository that are ready to be rendered. See RTD Build Process.
Related
I'm trying to stitch together doxygen and sphinx using breathe.
breathe requires you generate doxygen xml output first though: https://breathe.readthedocs.io/en/latest/quickstart.html
I don't want to do this in a separate step. Can I just have sphinx-build execute doxygen for me on build? I just need it to run this command first with some args. Is this possible without having to write a custom sphinx plugin?
EDIT
This works
# Need to sleep because sometimes doxygen doesnt finish writing files before sphinx runs
cwd = os.path.dirname(os.path.realpath(__file__))
os.system('doxygen')
time.sleep(3)
Sure, Sphinx will execute whatever Python code you add to its configuration file conf.py before it starts the documentation build process.
From the Sphinx documentation:
The configuration file is executed as Python code at build time (using importlib.import_module(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.
Which means pre-build tasks can simply be implemented by running the external program, such as Doxygen in your case, as a subprocess anywhere in conf.py.
I am using the primary GO extension.
I use VS code a lot, now I'm learning GO lang.
And when I open VS Code every time I'm getting this:
Error loading workspace: found module "main.go" twice in the workspace.
While running the code it's giving the right output.
I don't know how to fix this.
Anybody, help me with this error.
It would be better to open in VSCode only one folder with its own go.mod project.
A workspace with multiple go.mod/project should be supported with 1.18
The go command now supports a "Workspace" mode.
If a go.work file is found in the working directory or a parent directory, or one is specified using the -workfile flag, it will put the go command into workspace mode.
In workspace mode, the go.work file will be used to determine the set of main modules used as the roots for module resolution, instead of using the normally-found go.mod file to specify the single main module.
As described in "How to make VScode Go work in a Multi-Module Repo" from Varun Kumar, this used to work:
If you want to work with all the nested modules in a single workspace, there is an opt-in module feature that allows to work with multiple modules without creating workspace folders for each module. Set this in your settings -
"build.experimentalWorkspaceModule": true
But as per september 2022 is deprecated.
See more at gopls documentation "Setting up your workspace".
My first public Python project is now on readthedocs (RTD). There is one problem I'm trying to fix, but without success so far.
I'm using the :async: option to mark coroutines. This is supported by sphinx 2.1+. RTD used sphinx 1.8.5 for my project. All coroutines are simply skipped from the HTML output, i.e not documented at all. That is quite bad.
I created docs/requirements.txt file in my project containing: sphinx>=2.1.0 and in RTD > admin > advanced settings I have entered: /docs/requirements.txt as "A pip requirements file needed to build your documentation. Path from the root of your project.". Don't know if this is the right way to specifiy the sphinx version. Anyway I tried.
The build failed:
ERROR: Could not open requirements file: [Errno 2] No such file or directory: '../../../../../../../../docs/requirements.txt'
How could I overcome these problems to have all coroutines properly documented?
RTD cannot find your requirements file. Try specifying the path relative to the root of your project, not as absolute, by removing the leading slash.
I'm using DocPad to build my website, and in the docs it's saying that we can use an helper called buildr to bundle, compress files.
Is it possible to integrate buildr execution within the command docpad generate or docpad run?
Also does it needs it own config file buildr.coffee or it's possible to write the configs inside the docpad.config plugin section?
I imagine it would be more or less the same as this gist for grunt except with the grunt stuff changed to buildr.
I am reading on the article how to generate an Apple-like HTML documentation at here. My questions are what the command lines are used for. How can we combine command lines and appledoc xcode project to generate a HTML.
I'm the author of appledoc tool. The tool is intended to be used as answered by Caleb above. Recommended installation method is to clone repository from GitHub, open project in Xcode, build and optionally copy binary to your path as suggested above. Additionally, you must also copy template files required for running the tool to one of predefined paths. All the steps required are described in the readme file on appledoc page on GitHub, see Quick Install section.
There are also other methods for installing - all contribution from users:
You can use install-appledoc.sh script included in the git repository.
There's also homebrew recipe available, although it doesn't install template files to my understanding (see this link).
For any additional questions go to appledoc Google group. I just created it few days ago, so there's no content at the moment of this writing, but feel free to ask questions there.
I haven't used 'appledoc', but from a quick look at the page you linked it appears that it's an open-source command-line utility. So the first step will be to compile the 'appledoc' program itself, and then stick it in a directory that's in your path, such as /usr/local/bin or ~/bin/.
The next step is to try to use it to generate some documentation (assuming that you've already created the markdown files that it consumes). Open a terminal window, navigate to the directory where your files are, and then use the command given at the top of the page that you linked:
appledoc --project-name appledoc --project-company "Gentle Bytes" --company-id com.gentlebytes --output ~/help .
If you want to use 'appledoc' to regenerate your documentation every time you build some project, you can add a "Run Script" build phase to an existing target in your project, or create a new target just for documentation that has nothing but a "Run Script" build phase. Either way, the script in that phase should be shell script containing a command similar to the one above (though you'll probably want to specify the source directory explicitly rather than just using the 'current' directory, i.e. .).
As I found on this post, you can generate a complete HTML documentation of your code with this command line:
appledoc --project-name BabelCPP --project-company "My Name"
--company-id com.mycompany --no-create-docset --output ./doc/ .
The last "." is the path to your code.