Add support for generating Slate Docs in Markdown format

[AgronAerco]

Enhancement, feature request.

Allow people using SLATE web app (https://github.com/slatedocs/slate) to make use of documentation in source code to maintain one true source of documentation rather than constantly synchronizing source code and documentation.

Please provide an option to generate .md files for use in SLATE web app

Some utilities that convert files to slate-compatible .md files are the following two projects. They may be useful.

Widdershins adverb: https://github.com/mermade/widdershins swagger-to-slate npm: https://www.npmjs.com/package/swagger-to-slate?activeTab=code

[albert-github]

When I understand it from:

Please provide an option to generate .md files for use in SLATE web app

SLATE uses a set of markdown files to generate its output in HTML(?) format.

• Is this correct?

Have a look at the GENERATE_XML facility and the possibility to generate from this (by e.g. xslt) your own format. Another possibility is to change the layout and apply your own css (see e.g. https://www.doxygen.nl/manual/customize.html).

[doxygen]

@AgronAerco I'm also interested in the workflow you have in mind for this. Doxygen is like a compiler, in that it generates static output files given static source files. Suppose we would generate some markdown files, in the right format, such that they can be viewed (and edited?) in this SLATE web application, how is the result going to end up in the original source files?

If you are just looking for a way to have documentation and source code close together, try setting INLINE_SOURCES to YES.

[AgronAerco]

No. For us that use Doxygen and use implementation-first rather than contract-first approach, would like to keep using in-the-source-code type of documentation. And would like to have only one true source of documentation and that it is the way Doxygen is used right now. I would not use Slate or any tools to edit documentation. I would use the source code to edit documentation.

Therefore, it would be nice to develop notation such as '@brief' or '@param' etc, that generates Slate, Swagger, OpenAPI, OpenAsync type formatting for the functions that implement API endpoints.

Keeping the API docs in sync with source code is a huge and constant battle.

[albert-github]

Therefore, it would be nice to develop notation such as '@brief' or '@param' etc, that generates Slate, Swagger, OpenAPI, OpenAsync type formatting for the functions that implement API endpoints.

What do you mean here, what would you like to see here?

Keeping the API docs in sync with source code is a huge and constant battle.

That is a sure fact, but that is a by discipline of the developers and already aided by means of the fact (as you use it too) one source for code and documentation.

[AgronAerco]

For example: if something is marked as public api it may be included for Slate, Swagger, OpenAPI, OpenAsync generation, otherwise it goes only to regular doxygen document generation. public api's need to have a different target folder OUTPUT_DIRECTORY

//! \publicapi
//! \brief userManager::setUsername
//! \param uuid
//! \param newName
//! \return Function returns NEC of NEC_OK when the response to the HTTP client has been successfully sent
//! \server myweb.example.com:8080
//! \URL /website/user/setUsername
//! \protocols { HTTP1.1 | HTTP2 | HTTP3 | MQTT | MODBUS | BACNET | PROFIBUS }
//! \methods { GET  |  POST |  PUT | HEAD | DELETE | PATCH | OPTIONS | CONNECT | TRACE }
//! \apireturn application/json {
//!       "id": 7801,
//!       "status": "success",
//!       "statuscode": "1"
//!     }
//! \example in php
//! php example here
//! \example in javascript
//! javascript example here
//! \example in curl
//! curl example here
//! This endpoint will set the account identified via uuid to the username specified in the newName query parameter
NEC userManager::setUsername( UUID uuid /** [in] */, QString*newName  /** [in] */)
{
...
}

Doxygen would generate index.html.md file for slate, projectname.json (or yaml) for Swagger or OpenAPI and so on. Doxygen would not generate html or static documentation for Slate, Swagger, OpenAPI or OpenAsync for now because others are already doing it. However, very soon after people will ask for it.

Here's an example of what needed to to generate for Slate md file: