New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

LaTeX project for documentation like C++ ISO/IEC #1288

Closed
cogutvalera opened this Issue Aug 27, 2018 · 5 comments

Comments

Projects
None yet
4 participants
@cogutvalera
Member

cogutvalera commented Aug 27, 2018

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

This comment has been minimized.

pmconrad commented Aug 27, 2018

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

This comment has been minimized.

Member

cogutvalera commented Aug 27, 2018

@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

This comment has been minimized.

Member

cogutvalera commented Aug 28, 2018

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

This comment has been minimized.

Member

oxarbitrage commented Sep 27, 2018

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

This comment has been minimized.

Member

oxarbitrage commented Sep 28, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment