GitHub supports asciidoc readme files, but it looks like "include" is not supported.
I want to use doctoolchain which can render and export to html and pdf (and maybe into other formats). This tool works great.
I could use raw.githack.com to show the generated html file from the GitHub repository.
But I think it would be a good idea to have the result also as one (1) readme.adoc file.
How to export into one (1) asciidoc file, which I could use as it is as readme file so that github will render it and show? Best would be to use doctoolchain, when this tool will render my documentation it could also generate the one-file-asciidoc-documentation.
I think internally asciidoctor collects and merge all these "include" files. So maybe this file is already available in any place? The doctoolchain build folder contains only the target files.
You are right there is a long dicussion why includeis not supported by github.
You can achieve your goal with doctoolChain and pandoc(https://pandoc.org/). Following steps are required:
configure your docDir/Config.groovy
inputFiles should have docbook defined
inputFiles = [[file: 'yourfile', formats['docbook']]]
run the doctoolchain task generateDocbook - it creates ???.xml file somewhere in docDir/build
generate from the generated docbook again an asciidoctor file - `pandoc <FILENAME_OF_GENERATED_DOCBOOK.XML> -f docbook -t asciidoctor -o <FILENAME_OF_ASCIIDOCTOR_WHICH_HAS_EVERYTHING>
make sure it runs automatically and you commit it regulary
now you are ready
This script can be used to resolve includes and to generate one (1) output file:
https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb
some information about the script and possible next steps you can read here:
AsciiDoc Backend (AsciiDoc 2 AsciiDoc) for preprocessing
to use it, ruby and asciidoc must be installed:
asciidoctor.org/#installation
Related
My API documentation is getting quite large and I was wondering if it was possible to separate the openapi.yml file into separately managed chunks rather than having it all in one and have reDoc (or some other tool) combine it and then generate the HTML site.
Redoc has its own tool for that "Redoc CLI" npm #redocly/cli
checkout their tutorial https://github.com/Redocly/openapi-starter
with this tool you can:
split your actual docs with one command
(to paths, components, parameters, schema)
redocly split openapi.yaml --outDir openapi
lint them (separated files or final one)
redocly lint openapi/openapi.yaml
preview (with hot reloading on change)
redocly preview-docs openapi/openapi.yaml
and merge them back when production ready
redocly bundle openapi/openapi.yaml -o openapi.yaml
and even more...
Here is (more or less) the text in a sample script tag for EaselJS:
'script src="https://code.createjs.com/easeljs-0.8.2.min.js">
Note the file name: easeljs-0.8.2.min.js
But...when I download EaselJS from GitHub I can't find the equivalent file. The closest I can come is this: easeljs-NEXT.min.js.
I want to point to a client-side script, so that I can work off-line. Like this:
"script src='easeljs-0.8.2.min.js'' /script"
In the downloaded files from GitHub, which file is the correct one to point to in the src attribute for local use?
Have you gone to https://code.createjs.com? There are links to download all the versions of EaselJS libs.
You can also get the latest compiled libs in the lib/ folder on GitHub, or download any of the releases here: https://github.com/CreateJS/EaselJS/releases
I have written the documentation for a medium sized C++ piece of software using Doxygen together with Markdown. I am quite happy with it, as after changing the xml layer I ended up with something like that:
http://docs.mitk.org/nightly/index.html
I would like to bring this documentation online, ideally using something like ReadtheDocs, where the documentation would be automatically built after a "git commit", and hosted to be browsed.
ReadtheDocs looks like the ideal site but uses Sphinx and reStructuredText as defaults. Doxygen can be used too, but AFAIK only through Breathe. Going through that route essentially means that I would need to re-structure all the documentation if I don't want to dump all the API documentation into a single page (http://librelist.com/browser//breathe/2011/8/6/fwd-guidance-for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project/#cab3f36b1e4bb2294e2507acad71775f).
Paradoxically, Doxygen is installed in the read-the-docs server, but after struggling I could not find a workaround to skip its Sphinx or Mkdocs.
I've tried the following solution to use Doxygen on Read The Docs and it seems to work:
set up empty sphinx project (refer to official sphinx doc),
in sphinx conf.py add command to build doxygen documentation,
use conf.py html_extra_path config directive to overwrite generated doxygen documentation over generated sphinx documentation.
I've tested this with following source tree:
.../doc/Doxyfile
/build/html
/sphinx/conf.py
/sphinx/index.rst
/sphinx/...
Some explanation:
in my setup doxygen generates its documentation in "doc/build/html",
ReadTheDocs runs its commands in directory where it finds conf.py file.
What to do:
add following lines in conf.py to generate doxygen docs:
import subprocess
subprocess.call('cd .. ; doxygen', shell=True)
update conf.py html_extra_path directive to:
html_extra_path = ['../build/html']
In this configuration ReadTheDocs should properly generate and store Doxygen html documentation.
todo:
other documentation formats, for example: pdf.
This answer builds upon the great one already given by "kzeslaf". So follow the steps described by him first, before you continue here.
While his answer works as intended, I had the problem that ReadTheDocs (RTD) uses a rather old version of Doxygen (1.8.13 at the time of writing). This caused several issues for me like the one reported here. Additionally, if you set up Doxygen to treat warnings as errors, you might need to override this option on RTD due to version-related warnings.
I found a simple solution to upgrade the Doxygen version on RTD using conda.
Create an environment.yml file somewhere in your project (probably in the documentation directory). The content is as follows:
name: RTD
channels:
- conda-forge
- defaults
dependencies:
- python=3.8
- doxygen=<VERSION>
Replace <VERSION> with any version number that you like to use and that is available on conda-forge. Use conda search doxygen -c conda-forge to get a list of all available versions or simply check this site. You can also remove =<VERSION> and conda should install the latest one automatically.
Now you need to create an RTD config file if you haven't done this already. Add the following lines:
conda:
environment: <DIRECTORY>/environment.yml
Replace <DIRECTORY> with the actual location of the environment.yml file (relative to your project root, for example: docs/environment.yml). Now, if you followed all the steps in the answer of "kzelaf" and the ones I mentioned, RTD should successfully build your Doxygen documentation with the version you selected. You can check it in the lower right corner of the created pages. Alternatively, add subprocess.run(["doxygen", "-v"]) to your conf.py and check the RTD build logs.
Recently I started writing some doxygen docs in an existing project which already has quite a lot of doxygen comments.
Since I'm learning a bit - I like to iterate with making edits and generating docs, since doc generation is quite slow - 3-5min. This becomes un-workable.
I managed by deleting most of the files in the source tree so doxy only found the ones I was editing but this is really a horrible solution and not something I'd want to do frequently.
Is there a way (command line arg or env variable for eg) - to limit which files/modules are used for generating docs - so rebuilding docs can be done much faster?
Yes, you can customize Doxygen's behavior from either the command-line or via environment variables. For example, if you only want to include one file (include/somefile.h), you could execute Doxygen like:
( cat Doxyfile ; echo "INPUT=include/somefile.h" ) | doxygen -
see the Doxygen FAQ's "Can I configure doxygen from the command line?" for more details on customizing behavior from the command line.
Alternatively, if you want to use environment variables, you could use specify something like the following in your configuration file:
INPUT = $(FILE)
Doxygen performs environment variable substitution on its configuration files, allowing you to specify which file(s) should be acted on using:
export FILE=include/somefile.h
doxygen Doxyfile
See Doxygen Configuration for details on using environment variables in configuration files.
How can you ignore files by Doxygen similarly as by Git's .git/info/exclude?
Doxygen generates docs for me based on 3rd party codes such Email -component and of my Git -repo, which I do not want.
I need to keep the files where they are.
You can use the EXCLUDE_PATTERNS tag in the configuration file:
EXCLUDE_PATTERNS = */test/*
Taken from here.