LaTeX project for documentation like C++ ISO/IEC

[cogutvalera]

Instructions

• User Story
• Impacts
• Additional Context (optional)

User Story
As a developer I want to use LaTeX for BitShares API documentation like C++ ISO/IEC (https://github.com/cplusplus/draft) so that we can get all benefits from LaTeX system.

Additional Context (optional)
https://github.com/cplusplus/draft
https://github.com/cplusplus/reflection-ts
https://github.com/cplusplus/networking-ts
https://github.com/cplusplus/modules-ts

CORE TEAM TASK LIST

• Evaluate / Prioritize Feature Request
• Refine User Stories / Requirements
• Define Test Cases
• Design / Develop Solution
• Perform QA/Testing
• Update Documentation

[pmconrad]

Although I'm kind of a LaTeX fan I fail to see the benefits of this suggestion. LaTeX is great for producing print output. However, API documentation of live software is a moving target, therefore a printed representation is less than ideal. Searchable, indexable, up-to-date online documentation is the way to go IMO, and LaTex is not the right medium for this.

[cogutvalera]

@pmconrad thank you very much for your time and for your opinion ! Really appreciate it !
Cannot agree with you that LaTeX is great only for producing print output, what about C++ documentation ? I think LaTeX is good enough for any kind of technical documentation, of course maybe I'm wrong - it's just my own opinion. Let's discuss more about it and let's listen more opinions. Maybe you're absolutely right, but my feelings tell me that it can be nice approach and good quality way for BitShares technical documentation.

Official idea of LaTeX is described here https://www.latex-project.org/

LaTeX – A document preparation system
LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is the de facto standard for the communication and publication of scientific documents.

[cogutvalera]

http://pandoc.org/

If you need to convert files from one markup format into another, pandoc is your swiss-army knife. Pandoc can convert documents in (several dialects of) Markdown, reStructuredText, textile, HTML, DocBook, LaTeX, MediaWiki markup, TWiki markup, TikiWiki markup, Creole 1.0, Vimwiki markup, OPML, Emacs Org-Mode, Emacs Muse, txt2tags, Microsoft Word docx, LibreOffice ODT, EPUB, or Haddock markup

[oxarbitrage]

There is a discussion about apidocs here #792

It is true that doxygen is limited in regards to generate documentation for the api. One of the options was to add apidocs, swagger or similar but this will result with duplicated descriptions in the cpp files leading to a messy scenario.

Another option is to define the docs in a separated file, like https://github.com/oxarbitrage/bitshares-explorer-api/blob/master/swagger/paths_explorer.yaml. Swagger will read from the file and create http://148.251.10.231:5000/apidocs/
This still have the disadvantage of the maintenance of 2 files with documentation.

The discussion is pretty much on hold there but i don't see either how latex can help here.

[oxarbitrage]

i think this can be closed, Latex will not be made in the near future. Feel free to reopen if you think it is something to drive attention at this moment.