It's not a joke. I'm trying to see if I'm missing something. In the official documentation, I see only a description and the claim that the framework is well-documented. I wonder where is this excellent documentation?
I need to write a simple demo e-shop with a simple list of products and integration with ipayment.de. The list, I can do easily. But where do I read on how to integrate the ipayment form with the shop?
There's a doc/ directory in the git repository, which contains what looks like the source files for docs.satchless.com. You can cd into the doc/ directory and run make (you'll probably need to install Sphinx) to generate the HTML docs yourself.
It looks like, in addition to the index page you linked to, there is a file product.rst, which is amazingly not linked from index.rst (and thus product.html is not linked from index.html):
http://docs.satchless.com/en/latest/product.html
If that doesn't fulfil "well-documented", perhaps they mean it will be so? ;)
Related
I know there is way to copy static files via jsdoc, for images as example.
Is there a way to "extend" the generated template via markdown or html files that integrate into the "look & feel" of the used theme?
I know you can include one markdown file as "landing page", but i wonder if its possible to add more pages/files.
Why im asking this?
Because i want to generate the documentation out of my source code and add then some additional pages which describe the workflow of my application or the behavior of some components.
Doing this in a single markdown document & that as "landing page" seems not a good solution.
I cant imagine that there exist not a "read to use" solution.
I just want a nice & complete documentation of my application which includes stuff from the source code and additional pages.
Any hint is welcome.
Thanks in Advance.
I'm using sphinx and RST to generate some tech documentation as HTML and having issues getting a local PDF reference to work as a hyperlink. I've seen people use :download: to link to local PDFs, but I'm embedding the PDFs inside a /docs directory for reference. I don't like :download: because it doesn't display the PDF inline in the browser which requires an extra step on the users' behalf for consumption.
sphinx-build -b html does not copy any files unless they are specified in config.py hook html_static_path or html_extra_path - and even then they are dropped to the root directory or _static folders.
Is there a suggested approach for embedding linked binary files within sphinx or is this a poor practice? Often times the links are to slide decks or design diagrams that are not hosted anywhere else.
Sample RST for linked PDF
.. important:: View the agile course on scrum basics
- View `these slides to dive deeper into Agile Basics <docs/agile-101.pdf>`_.
The solution I came up with was to just add the PDFs to html_static_path and reference the _static output path in the link instead of the docs path where it lives in the source. Now PDFs open up in the browser instead of having to download them to view.
Would be great if there was an sphinx extension / directive to handle this (:download-inline:).
conf.py
html_static_path = ['_static', 'agile-101/docs']
agile-101.rst
.. important:: View the agile course on scrum basics
- View `these slides to dive deeper into Agile Basics <../_static/agile-101.pdf>`_.
I'm working on a C++ project and really fell in love with the Sphinx documentation build system. I managed to setup Doxygen and Breathe to produce and provide the C++ descriptions to Sphinx.
I can't figure out how Google's Ceres Solver documentation was done. Their API reference for example contains class names followed by lots of text, sometimes even with code block examples as shown in the previous link. Is there a way to write Doxygen documentation inside the source files and achieve this?
Another example is this class documentation, which has around two pages of text. I somehow doubt that all this text is located in the source files as Doxygen comments. I have the feeling that all the extra text has been written in the restructured text sources for the documentation and nothing in the c++ source files. But then what is the point of using doxygen and breathe...
Or asked differently, where should I put high-level information about the code? I mean I can document class1 and class2 in their sources, but somewhere I need to explain how both of them interact and are used together. This is what the documentation of the Ceres Solver does so nicely in my opinion.
Alternatively you could point me to a C++ project with the Sphinx + Doxygen + Breathe pipeline and open source documentation. Then I can see for myself how to do these things. Unfortunately I don't know about any project.
I missed the github link for the Ceres Solver. There the sources of the documentation can be found. I'm a bit disappointed, because the complete documentation is written in the Restructured Text source files and NOT inside the c++ code. Basically they reference the class name with .. class:: className and then add ReST markdown for informative text, example code blocks etc. One example is given in "Modeling Non-linear Least Squares"
I work on unix.
I have my complete source code in unix in the form of building blocks and modules.
Like headers,sources files,make files etc.
I can copy all the files with the same directory structure to windows.
I need some tool which will convert all the source to html tags with all the links to functions,variables,classes,headers.There should be some tool to do this easily.
by this way it would be easy for debugging the code in a fast way.
Is anybody aware of such tool?
The term you're probably looking for is "documentation generator". You're specifically interested in ones that output HTML files.
Doxygen is popular, but if you want a master comparison list of documentation generators Wikipedia has a summary:
http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
Looking at the output generated by the different programs (on projects that use them) will probably inform your choice of which meets your needs.
You can use doxygen to generate your documentation. In its basic form it will generate what you need but to add comments that appear in the final html you will need to use special style comments.
I'm going to manage some documentation using Django (I come from Sphinx) in order to have more control on the output. The docs are in rst (restructured text) in a git archive, and it's trivial to display them in HTML using a filter. My problem is that they are quite long, and I'd like to have more control on how the pagination goes, so I can show a single section per HTML page, have comments for a single section and so on...
My goal would be to be able to parse each doc, create my TOC with links to each section in a separate HMTL page, where a view would go through whole doc to render in html just a section.
I understand that it's mostly a issue of docutils, the most interesting example I've been able to find is: http://www.ibm.com/developerworks/library/x-matters24/#code2 but it seems outdated and the examples in section "Tree-oriented processing", which is where the magic goes, don't seem work with my version of docutils. Article is good: I could use more of the same subject!
Is there something similar to what I'm planning to do already available that I can study, or maybe could someone point me to a gentle introduction to docutils for parsing rst documents?
Here is a blog describing howto make a custom rst writer and call it from Django. I think it should give you a good start http://www.arnebrodowski.de/blog/write-your-own-restructuredtext-writer.html
Pygments has a ReST lexer that you could examine (or possibly even use directly).