mikelemo commented 3 years ago

How do you set this file? does it have to output latex? xml? can it accept warnings or other stuff? also where do things have to be in relation to each other in term of directory?

pieterdavid commented 3 years ago

Doxygen should be set up to generate html (other formats can be there, but will be ignored. Only the doxygen status code is checked - it is called from here). If the plugin is configured correctly to find the doxygen configuration file (see the last example here for a case where it is not in the project root) it should be able to find out where to get the HTML output from (this line should be able to either read it from the configuration file, or put in the defaults).

mikelemo commented 3 years ago

So where exactly do you install the plugin? does it have to be renamed afterwards? how to intigrate the doxygen outputs in markdown if you can't do that in rst?

I've got this plugins section on my mkdocs.yml:

plugins:
    - search
    - mermaid2
    - table-reader
    - doxygen:
      tryclone: no
      recursive: yes
      packages:
        - doxygen:
            url    : doxygen
        - doxyfwk:
            url    : https://github.com/cp3-llbb/Framework.git
            config : docs/doxygen.cfg
            workdir: . ## could be left out in this case

Does it suppose to have problems?

my doxygenfile is at "mkdocs/docs/doxygen.cfg" and mkdocs.yml @ "mkdocs/mkdocs.yml" Doxygen OUTPUT_DIRECTORY is set to ..\site\doxygen and HEML_GENERATION is set to YES

still getting errors like 👍

ERROR - Config value: 'plugins'. Error: Invalid Plugins configuration

Aborted with 1 Configuration Errors!

pieterdavid commented 3 years ago

pip install git+https://github.com/pieterdavid/mkdocs-doxygen-plugin.git#egg=mkdocs-doxygen-plugin (or the equivalent for how you manage python packages in the environment where mkdocs runs) should be sufficient. Based on your description I would start with this configuration:

plugins:
  - search
  - mermaid2
  - table-reader
  - doxygen:
      packages:
        - doxygen:
            url: .
            config: docs/doxygen.cfg

The Doxygen HTML output will just be put in a subdirectory of the mkdocs site (with the name of the package, so in the example above you can change the 'doxygen' under 'packages' to customise that), no other integration is done (the case for which I wrote the plugin just uses the HTML as part of the mkdocs site, the relevant mkdocs.yml fragments for that are this and this - the site is here, doxygen link under Framework > Doxygen on the left).

mikelemo commented 3 years ago

Ok Got it to work and from what I see it just it builds it with the normal doxygen theme instead of the read the docs one like the main used one and doesn't update the docs automatically when it detects changes in the sourcecode files which could be a nice addition I've came across the tools to do that with doxygen breathe and sphinx but these method uses rst and XML output from doxygen

I've made a rough code doc doc here:

Doxygen

In order to display formula vanila use mathjax(untill the main issue is sorted)
set in doxygen tab Expert->HTML --> USE_MATHJAX

Setup sphinx C documentating

Install theme


pip install sphinx-rtd-theme
pip install breathe
pip3 install sphinx-sitemap


# Generate sphinx read the doct reStructuredText documents

* Create documentation directroy:

mkdir docs_sphinx cd docs_sphinx


* Fireup sphinx quick start:

sphinx-quickstart


Follow the prompts. I chose: 

Separate directories: n

Project name: C++ Sphinx Doxygen Breathe

Author name(s): me

Project release: []

Language: english

Your directory docs_sphinx should look like this:

Makefile _build/ _static/ _templates/ conf.py index.rst make.bat


* Add to CMakeLists.txt in main project folder?

Doxygen

look for Doxygen package

find_package(Doxygen)

if (DOXYGEN_FOUND)

set input and output files

set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/docs_doxygen/Doxyfile.in)
set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.out)

# request to configure the file
configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
message("Doxygen build started")

# Note: do not put "ALL" - this builds docs together with application EVERY TIME!
add_custom_target( docs
    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
    COMMENT "Generating API documentation with Doxygen"
    VERBATIM )

else (DOXYGEN_FOUND) message("Doxygen need to be installed to generate the doxygen documentation") endif (DOXYGEN_FOUND)


* Edit `index.rst` with:

.. C test prj documentation master file, created by sphinx-quickstart on Sun Apr 18 22:05:10 2021. You can adapt this file completely to your liking, but it should at least contain the root toctree directive.

Welcome to C test prj's documentation!

.. toctree:: :maxdepth: 2 :caption: Contents:

myrst

Indices and tables

:ref:genindex
:ref:modindex
:ref:search


* Create `myrst.rst` with:
```rst

=====
MyRST
=====

for functions
.. doxygenfile::  lora_ebyte.c
   :project: vpr

   or (for all definitions)

.. doxygenfile::  include/lora_ebyte.h
   :project: vpr

edit conf.py to:


# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
from sphinx.builders.html import StandaloneHTMLBuilder
import subprocess, os

# Doxygen
subprocess.call('doxygen Doxyfile.dox', shell=True)

# -- Project information -----------------------------------------------------

project = 'Verilog to Routing - VPR'
copyright = '2020, me'
author = 'me'

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.autosectionlabel',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx_sitemap',
    'sphinx.ext.inheritance_diagram',
    'breathe'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

highlight_language = 'c'

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    'canonical_url': '',
    'analytics_id': '',  #  Provided by Google in your dashboard
    'display_version': True,
    'prev_next_buttons_location': 'bottom',
    'style_external_links': False,

    'logo_only': False,

    # Toc options
    'collapse_navigation': True,
    'sticky_navigation': True,
    'navigation_depth': 4,
    'includehidden': True,
    'titles_only': False
}
# html_logo = ''
# github_url = ''
# html_baseurl = ''

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# -- Breathe configuration -------------------------------------------------

breathe_projects = {
    "vpr"          : "_build/doxygen/vpr/xml",
    "abc"          : "../_build/doxygen/abc/xml",
    "ace2"         : "../_build/doxygen/ace2/xml",
    "ODIN_II"      : "../_build/doxygen/ODIN_II/xml",
    "blifexplorer" : "../_build/doxygen/blifexplorer/xml",
}

breathe_default_project = "Verilog to Routing - VPR"
breathe_default_members = ('members', 'undoc-members')

Create doxygen_template.dox file with command:

    doxygen -g doxyfile.dox

edit doxyfile.dox with the collosing settings:

PROJECT_NAME           = "Verilog to Routing - VPR"
OUTPUT_DIRECTORY       = _build/doxygen/vpr
FULL_PATH_NAMES        = NO
OPTIMIZE_OUTPUT_FOR_C  = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
WARN_IF_UNDOCUMENTED   = NO
INPUT                  = ../
RECURSIVE              = YES
GENERATE_HTML          = NO
GENERATE_LATEX         = NO
GENERATE_XML           = YES

I Like

ALPHABETICAL_INDEX  = NO

DISABLE_INDEX = YES GENERATE_TREEVIEW = YES

Ticking no to preproceccing will remoce all the define and macros from H displaying only the functions ENABLE_PREPROCESSING = NO

For C proceccing CLASS_DIAGRAMS = NO

Then finally
```
make html
```

to generate html web which builds it according to directives & config variable More at breate documentation index.rst or(in our particular example) myrst.rst

Can be found @ projectFolder/doc_sphins/_build/html/index.html

sOURCES:

https://embeddedinventor.com/guide-to-configure-doxygen-to-document-c-source-code-for-beginners/ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Autobuild documentation

pip install sphinx-autobuild

Render current folder out html to _build/html
sphinx-autobuild .. _build/html

Autodoc?
Intersphinx

pieterdavid / mkdocs-doxygen-plugin

Setting up the doxygen.conf file? #3

Doxygen

Setup sphinx C documentating

Doxygen

look for Doxygen package

set input and output files

Welcome to C test prj's documentation!

Indices and tables

sOURCES:

Autobuild documentation