I have done some experiments with writing programs that are also at the same time valid documentation that can be rendered as README's by e.g. Github - this ensures that code snippets are up to date and valid - and had some very interesting findings with Markdown. Unfortunately that format does not support having an automatically generated table of contents, so we looked into AsciiDoc which does.
I managed to copy an example using :toc: macro (to be able to place it after the opening summary), and then went on to make it valid Java, which essentially mean that you have to start the file with the /* characters but then I cannot make the table of contents appear any more.
The snippet starts with:
= Asciidoctor PDF Theming Guide
Dan Allen <https://github.com/mojavelinux[#mojavelinux]>
// Settings:
:idprefix:
:idseparator: -
:toc: macro
:experimental:
ifndef::env-github[:icons: font]
ifdef::env-github[]
:outfilesuffix: .adoc
:!toc-title:
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
:window: _blank
// Aliases:
:conum-guard-yaml: #
ifndef::icons[:conum-guard-yaml: # #]
ifdef::backend-pdf[:conum-guard-yaml: # #]
:url-fontforge: https://fontforge.github.io/en-US/
:url-fontforge-scripting: https://fontforge.github.io/en-US/documentation/scripting/
:url-prawn: http://prawnpdf.org
////
Topics remaining to document:
* line height and line height length (and what that all means)
* title page layout / title page images (logo & background)
////
[.lead]
The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file
... blurb removed ...
/* (Experiment with asciidoc)
= Dagger 2 Hello World
// (Important: As an experiment Main.java is also a valid markdown file copied unmodified to README.md, so only edit Main.java)
This project is a single file Hello World Dagger-2 Maven project for
Java 8 and later, while also being its own documentation written in AsciiDoc.
toc::[]
My gut feeling is that the TOC does only work as expected if the file starts with lines parsed by AsciiDoc where this is set up and configured. If any output is generated before the configuration bits (like the Java comment) then the TOC is silently empty.
Hence I would like to know how I should do this correctly. All I want is a functional toc::[] macro in a file starting with /*
Asciidoc markup files are not Java source files. While I understand that this would be a compelling combination of the formats, that capability does not exist.
To keep source files up-to-date, your Asciidoc source files can use the include directive to include a source file. See: https://asciidoctor.org/docs/user-manual/#include-directive
To include, say, a single method, you can use tags to mark the start and end of the method's implementation, and then you can include that tag-delimited code section like this:
[source,java]
----
include::path/to/source.java[tag="method-x"]
----
Note that if the path to the Java source that you want to include is outside of the current directory, you may have to change the safe mode accordingly: https://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely
Related
How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?
The expression "reST/Sphinx" makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I'm going to cover both since people using RST are likely to run into both cases at some point:
Sphinx
Besides the domain-specific directives that can be used to link to various entities like classes (:class:) there's the general :ref: directive, documented here. They give this example:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Although the general hyperlinking mechanism offered by RST does work in Sphinx, the documentation recommends against using it when using Sphinx:
Using ref is advised over standard reStructuredText links to sections (like Section title_) because it works across files, when section headings are changed, and for all builders that support cross-references.
RST, in General
The tools that convert RST files to HTML do not necessarily have a notion of collection. This is the case for instance if you rely on github to convert RST files to HTML or if you use a command line tool like rst2html. Unfortunately, the various methods to use to get the desired result vary depending on which tool you are using. For instance, if you use rst2html and you want file A.rst to link to a section named "Section" in file other.rst and you want the final HTML to work in a browser, then A.rst would contain:
`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.
You have to link to the final HTML file and you have to know what the id given to the section will be. If you want to do the same for a file served through github:
`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.
Here too you need to know the id given to the section. However, you link to the RST file because it is only upon accessing the RST file that the HTML is created. (At the time of writing this answer, accessing the HTML directly is not allowed.)
A complete example is available here.
New, better answer for 2016!
The autosection extension lets you do this easily.
=============
Some Document
=============
Internal Headline
=================
then, later...
===============
Some Other Doc
===============
A link- :ref:`Internal Headline`
This extension is built-in, so all you need is to edit conf.py
extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]
The only thing you have to be careful of is that now you can't duplicate internal headlines across the doc collection. (Worth it.)
Example:
Hey, read the :ref:`Installation:Homebrew` section.
where Homebrew is a section inside a different document named Installation.rst.
This uses the autosection feature, so will need to edit config.py with the following:
extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
In Sphinx 3.0.3 the only solution that worked for me is :any: (see https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything).
Suppose, one document has such a section:
.. _my-section:
My Section
----------
Lorem ipsum blablabla
Then another document can have the following fragment to create a link:
See :any:`my-section` for the details
I was struggling to make this work and i found out that the actual notation is :ref:'{dir-path}/Installation:Homebrew' where {dir-path} is the relative path to Installation.rst from where config.py exists
Adding description of behavior that was confusing to me.
Section titles must be referenced with the file name (overview here) in front of it:
overview.rst:
************
API Overview
************
index.rst:
:ref:`overview:API Overview`
However, when referencing links, the file name (constants here) must not be there:
constants.rst:
.. _section-constants:
*******************
Enums and Constants
*******************
api.rst:
:ref:`section-constants`
Also, for this to work, one must enable extension 'autosectionlabel':
conf.py:
extensions = [
...
"sphinx.ext.autosectionlabel"
]
How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?
The expression "reST/Sphinx" makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I'm going to cover both since people using RST are likely to run into both cases at some point:
Sphinx
Besides the domain-specific directives that can be used to link to various entities like classes (:class:) there's the general :ref: directive, documented here. They give this example:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Although the general hyperlinking mechanism offered by RST does work in Sphinx, the documentation recommends against using it when using Sphinx:
Using ref is advised over standard reStructuredText links to sections (like Section title_) because it works across files, when section headings are changed, and for all builders that support cross-references.
RST, in General
The tools that convert RST files to HTML do not necessarily have a notion of collection. This is the case for instance if you rely on github to convert RST files to HTML or if you use a command line tool like rst2html. Unfortunately, the various methods to use to get the desired result vary depending on which tool you are using. For instance, if you use rst2html and you want file A.rst to link to a section named "Section" in file other.rst and you want the final HTML to work in a browser, then A.rst would contain:
`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.
You have to link to the final HTML file and you have to know what the id given to the section will be. If you want to do the same for a file served through github:
`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.
Here too you need to know the id given to the section. However, you link to the RST file because it is only upon accessing the RST file that the HTML is created. (At the time of writing this answer, accessing the HTML directly is not allowed.)
A complete example is available here.
New, better answer for 2016!
The autosection extension lets you do this easily.
=============
Some Document
=============
Internal Headline
=================
then, later...
===============
Some Other Doc
===============
A link- :ref:`Internal Headline`
This extension is built-in, so all you need is to edit conf.py
extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]
The only thing you have to be careful of is that now you can't duplicate internal headlines across the doc collection. (Worth it.)
Example:
Hey, read the :ref:`Installation:Homebrew` section.
where Homebrew is a section inside a different document named Installation.rst.
This uses the autosection feature, so will need to edit config.py with the following:
extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
In Sphinx 3.0.3 the only solution that worked for me is :any: (see https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything).
Suppose, one document has such a section:
.. _my-section:
My Section
----------
Lorem ipsum blablabla
Then another document can have the following fragment to create a link:
See :any:`my-section` for the details
I was struggling to make this work and i found out that the actual notation is :ref:'{dir-path}/Installation:Homebrew' where {dir-path} is the relative path to Installation.rst from where config.py exists
Adding description of behavior that was confusing to me.
Section titles must be referenced with the file name (overview here) in front of it:
overview.rst:
************
API Overview
************
index.rst:
:ref:`overview:API Overview`
However, when referencing links, the file name (constants here) must not be there:
constants.rst:
.. _section-constants:
*******************
Enums and Constants
*******************
api.rst:
:ref:`section-constants`
Also, for this to work, one must enable extension 'autosectionlabel':
conf.py:
extensions = [
...
"sphinx.ext.autosectionlabel"
]
Context
I am making a script that dynamically inserts include directives in code blocks on an AsciiDoc file and then generates a PDF out of that. A generated AsciiDoc file could look like this:
= Title
[source,java]
---
include::foo.java[]
---
I want the user to be free to include whatever char-based file he or she wants, even other AsciiDoc files.
Problems
My goal is to show the contents as are of these included files. I run into problems when the included file:
is recognized as AsciiDoc beacuse of its extension, an thus any include directives it has are interpreted. I don't want nested includes, just to show the include directive in the code block. Example of undesired behaviour:
contains the code block delimiter ----, as seen on the image above when I end up with two code blocks instead of the intended single one. In this case, it does not matter if the file is recognized as an AsciiDoc file, the problem persists.
My workaround
The script I am writing uses AsciidoctorJ and I am leveraging that I can control how the content of each file is included by using an include processor. Using the include processor I wrap each line of each file with the pass:[] macro. Additionally, I activate macro substitution on the desired code block. A demonstration of this idea is shown in the image above.
Is there a better way to show the exact contents of a file? This works, but it seems like a hack. I would much rather prefer not having to change the read lines as I am currently doing.
EDIT for futher information
I would like to:
not have to escape the block delimiter. I am not exclusively referring to ----, but whatever the delimiter happens to be. For example, the answer by cirrus still has the problem when a line of the included file has .....
not have to escape the include directives in files recognized as AsciiDoc.
In a general note, I don't want to escape (or modify in any way) any lines.
Problem I found with my workaround:
If the last char of a line is a backslash (\), it escapes the closing bracket of the pass:[] macro.
You can try using a literal block. Based on your above example:
a.adoc:
= Title
....
include::c.adoc[]
....
If you use include:: in c.adoc, asciidoctor will still try to find and include the file. As such you will need to replace include:: with \include::
c.adoc:
\include::foo.txt[]
----
----
Which should output the following pdf:
I'm writing a shell script (.sh) to:
Convert a markdown file (README.md) to HTML
Convert a HTML file to latex.
Convert a latex file to PDF.
The shell script uses MultiMarkdown v6 (by Fletcher Penney) for step 1-2 and "pdflatex" for step 3. The files are generated and formatted automatically.
The PDF pages are numbered, however, the pages in the table of content are not and question marks appear in the toc.
I included the metadata at the very top of the README.md. The script uses metadata to generate the latex file. I created the toc using the usual method for Github readme.md.
MMDv6 provides the "{{TOC}} function" (I did not use it). I could not get my head around this function so I just created a toc using the method I mentioned above.
MultiMarkdown User's Guide has a small section about toc (https://fletcher.github.io/MultiMarkdown-6/MMD_Users_Guide.html#tableofcontents).
Useful info about MMD & Latex
(https://github.com/fletcher/MultiMarkdown/wiki/MultiMarkdown-and-LaTeX)
My table of content has the following structure:
Table of Contents
=================
<!--ts-->
1. [Abstract](#Abstract)
2. [Table of Contents](#Table-of-Contents)
3. [System Installation](#System-Installation)
4. [System Architecture](#System-Architecture)
etc...
The script runs well, however, I would expect page numbers in the toc.
The toc on the PDF looks like:
Abstract (??)
System Installation (??)
System Architecture (??)
where (??) corresponds to the page number. How can I fix this? Do you have any suggestion?
Thanks
How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?
The expression "reST/Sphinx" makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I'm going to cover both since people using RST are likely to run into both cases at some point:
Sphinx
Besides the domain-specific directives that can be used to link to various entities like classes (:class:) there's the general :ref: directive, documented here. They give this example:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Although the general hyperlinking mechanism offered by RST does work in Sphinx, the documentation recommends against using it when using Sphinx:
Using ref is advised over standard reStructuredText links to sections (like Section title_) because it works across files, when section headings are changed, and for all builders that support cross-references.
RST, in General
The tools that convert RST files to HTML do not necessarily have a notion of collection. This is the case for instance if you rely on github to convert RST files to HTML or if you use a command line tool like rst2html. Unfortunately, the various methods to use to get the desired result vary depending on which tool you are using. For instance, if you use rst2html and you want file A.rst to link to a section named "Section" in file other.rst and you want the final HTML to work in a browser, then A.rst would contain:
`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.
You have to link to the final HTML file and you have to know what the id given to the section will be. If you want to do the same for a file served through github:
`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.
Here too you need to know the id given to the section. However, you link to the RST file because it is only upon accessing the RST file that the HTML is created. (At the time of writing this answer, accessing the HTML directly is not allowed.)
A complete example is available here.
New, better answer for 2016!
The autosection extension lets you do this easily.
=============
Some Document
=============
Internal Headline
=================
then, later...
===============
Some Other Doc
===============
A link- :ref:`Internal Headline`
This extension is built-in, so all you need is to edit conf.py
extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]
The only thing you have to be careful of is that now you can't duplicate internal headlines across the doc collection. (Worth it.)
Example:
Hey, read the :ref:`Installation:Homebrew` section.
where Homebrew is a section inside a different document named Installation.rst.
This uses the autosection feature, so will need to edit config.py with the following:
extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
In Sphinx 3.0.3 the only solution that worked for me is :any: (see https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything).
Suppose, one document has such a section:
.. _my-section:
My Section
----------
Lorem ipsum blablabla
Then another document can have the following fragment to create a link:
See :any:`my-section` for the details
I was struggling to make this work and i found out that the actual notation is :ref:'{dir-path}/Installation:Homebrew' where {dir-path} is the relative path to Installation.rst from where config.py exists
Adding description of behavior that was confusing to me.
Section titles must be referenced with the file name (overview here) in front of it:
overview.rst:
************
API Overview
************
index.rst:
:ref:`overview:API Overview`
However, when referencing links, the file name (constants here) must not be there:
constants.rst:
.. _section-constants:
*******************
Enums and Constants
*******************
api.rst:
:ref:`section-constants`
Also, for this to work, one must enable extension 'autosectionlabel':
conf.py:
extensions = [
...
"sphinx.ext.autosectionlabel"
]