It looks like the only way to define an example in doxygen is to put it in a separate file. The documentation can be found here.
Is it possible to define the example directly inside the doxygen comment?
Using a \code tag works good for me:
<b>Example</b>
\code{.c}
...
\endcode
Related
I'm rather new to Sphinx and ReST and I've "inherited" a big project.
The documentation consists of hundreds of pages with how to's, etc. There are several files (one for each class) where the respective functions are described using the ".. py:function::" directive.
So each of these pages is basically like this:
Some description text explaining the class
py:function:: class.myFunction(param1, param2)
parameter description
code example, ...
py:function:: class.myFunction2
parameter description
code example, ...
Now, I'd like to list all functions of all different pages in one single XML file, if possible grouped by their class, but without the descriptions and examples. Is this possible with some built-in Sphinx parser or do I have to write my own? Or is there any other directive or config option that may be helpful?
The XML file should be like this:
<class1>
<function1>
<param1>
<param2>
...
<function2>
...
<class2>
<function1>
...
I found ViewLists and the Parsing directive in the Sphinx documentation but i'm not sure how to correctly use them and if that's the solution to my problem.
I would like to separate each change of the databaseChangeLog in YAML format into its own file (again YAML) and include/import it somehow. It should be in way such that I can use a FileSystemAccessor or ClassPathAccessor to load it again.
Is there some example how to do that?
Thanks,
Dieter
The way to do this is described at https://www.liquibase.org/bestpractices.html
The example given shows XML formatted changelogs, but the basic idea would be the same for YAML formatted changelogs.
Leave me a comment and I can generate a sample in YAML.
After some searching I found this on the liquibase repo:
https://github.com/liquibase/liquibase/blob/master/liquibase-core/src/test/resources/liquibase/parser/core/yaml/doubleNestedChangeLog.yaml
It is an example how you can separate your yaml files analog to the xml as shown by SteveDonies link.
I am using Spring RestDoc together with AsciiDoc to describe my rest api. RestDoc generates different files depending if there are request parameters described / response fields etc. I would like to have one template conditionally including whatever file exists.
something like this:
Request:
include::{reqresPath}/http-request.adoc[]
Response:
include::{reqresPath}/http-response.adoc[]
Parameters:
ifeval::[{{reqresPath}/request-parameters.adoc}.exists]
include::{reqresPath}/request-parameters.adoc[]
endif::[]
ifeval::[{{reqresPath}/request-parameters.adoc}.exists]
include::{reqresPath}/request-parameters.adoc[]
endif::[]
or at least exclude warnings in case of a missing file. But I could not figure out how to suppress these.
As of today, where is no operator for ifeval available, which can be used to check the existence of a file.
The way I would go is to write an extension for Asciidoctor, which can also be done by using Java. If your projects is big enough, I would suggest to go for this solution.
The most extreme way is to make a custom TemplatedSnippet which is generating an empty snippet to be included...
I hope there is a better way to do this.
Edit:
Take a look of http://asciidoctor.org/docs/user-manual/#by-tagged-regions
I typically put the high-level documentation for a Python package into the docstring of its __init__.py file. This makes sense to me, given that the __init__.py file represents the package's interface with the outside world. (And, really, where else would you put it?)
So, I was really quite surprised when I fired up Sphinx for the first time and saw this content buried near the very end of the package documentation, after the content for all of the submodules.
This seems backward to me. The very first thing the user will see when he visits the page for a package is the documentation of the submodule that just happens to come first alphabetically, and the thing he should see first is right near the bottom.
I wonder if there is a way to fix this, to make the stuff inside of __init__.py come out first, before all of the stuff in the submodules. And if I am just going about this in the wrong way, I want to know that. Thanks!
Updated Answer (thank you, Donal Fellows):
https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#cmdoption-sphinx-apidoc-M
Original Answer:
Yes, there is an option to do this, it's just not documented here. Inside my copy of Sphinx-1.3.3/sphinx/apidoc.py I found this:
parser.add_option('-M', '--module-first', action='store_true',
dest='modulefirst',
help='Put module documentation before submodule '
'documentation')
I tried it and it works like a charm.
It is also possible to add this option in the conf.py file.
Search in conf.py for the line where the string containing the sphinx-apidoc command is (located in a try section) and add the "--module-first" option.
The new line will look like this:
cmd_line_template = "sphinx-apidoc --module-first -f -o {outputdir} {moduledir}"
Hadn't used Sphinx in a while, but it does seem like they've done a good job updating it. In the past, I had to manually specify the classes since I didn't like how autodoc generated the methods/functions. Now it does seem like you can order them:
.. autoclass:: YourClass
:members: __init__, __getitem__
http://www.sphinx-doc.org/en/stable/ext/autodoc.html
In Sphinx, if I have the following heading declaration:
.. _somestuff:
``this is code``, this is not!
==============================
It renders, like this:
this is code, this is not!
Which is good, but, if I use the reference, e.g:
Have a look at :ref:`somestuff`
It loses the code formatting and renders like:
Have a look at this is code, this is not!
instead of:
Have a look at this is code, this is not!
Is it possible to retain the code formatting in the reference? And how would I go about it?
If you have a look at :ref: documentation in its official web site about inline markups:
:ref:
To support cross-referencing to arbitrary locations in any document,
the standard reST labels are used. For this to work label names must
be unique throughout the entire documentation ...
I think (as #Kevin Horn) it's no possible right now, because it's only used to create links (without rst formatting) with other sections in your project. Then if you write something like this:
.. _somestuff:
``this is code``, this is not!
==============================
.. _another_somestuff:
this is another code!
========================
If I link with these sections:
Have a look at :ref:`somestuff`
Have a look at :ref:`another_somestuff`
Have a look at :ref:`this link <somestuff>`
The result is:
Have a look at this is code, this is not!
Have a look at this is another code!
Have a look at this link
The style is the same in all of them .
Note: the italic/bold words symbolize links