Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I maintain a small library project written in C++.
I'd like to use Sphinx to maintain the library website + user documentation per release version. I have found [similar question asked How to manage many versions? on the sphinx-dev mailing list which I have bumped but without extensive follow-up.
How to manage many versions?
I think of basic structure like this:
mylib/ <- website root
mylib/...
mylib/tutorial/...
mylib/doc <- list of documentation per release version
mylib/doc/1.0.0
mylib/doc/2.0.0
mylib/doc/X.Y.Z
I'm trying to figure out best practical configuration for this structure.
I have root configuration mylib/conf.py where I control the website structure and content.
I could put .rst files into mylib/doc/1.0.0 and mylib/doc/2.0.0 build them using the root conf.py. But then it seems tricky to control toctree for website and for docs.
So, I think it may be more practical to separate website config/build from per release documentation config/builds:
mylib/conf.py
mylib/doc/1.0.0/conf.py
mylib/doc/2.0.0/conf.py
mylib/doc/X.Y.Z/conf.py
but I'd like the main documents in mylib/doc/X.Y.Z/conf.py to use the same layout is the root documents in mylib/, so I can have consistent look, e.g. links in page header, etc.
This way I can easily achieve consistent toctree per documentation release.
It should be easy to walk the directories and perform builds for website and for each doc version separately.
Regarding searching the documentation, I don't mind the search engine to scan all versions of documentation per single query as well as I don't mind to have search engine specific to particular version (search box is displayed in the same place, but depending what is being read, it scans index of current version only).
Is there any better way to achieve that?
I've found similar question asked in sphinx for multiple, separate documents and I'm wondering if the Intersphinx plugin is a good idea here.
UPDATE:
2017-04-10: SO answer pointing to an interesting Sphinx extension: sphinxcobtrib-versioning
2011-10-21: Following olt's question in comments, mylib/ is not how I mean to structure project in VCS. So, I don't want to maintain multiple versions of documentation in VCS. The mylib/ is just structure for easier visualisation. It can be also working directory where I put Sphinx sources together (e.g. pull from version branches, etc.) and where I launch Sphinx to build the output.
In my opinion, the documentation should stay with the code in the same repository. Otherwise you would need to manage the documentation source manually, for example when you backport a feature from version B to A. With a single repository, you just check out that version and re-build the documentation.
You should look at SQLAlchemy project, they have multiple versions of their documentation available on the same site. The documentation is in the same repository and they copy the output of each version into their static homepage folders.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
During the development of my projects I find myself producing some large documents with slight variations on only a few paragraphs. For instance, the same configuration plan will be used throughout different projects but each document has to be tailored with specific data and to comply with some specific requirements.
Being a lazy person and a fan of model-driven development, I have been looking for ways to optimize this process and I got these options:
Document templates - Using master document templates (the presentation) with forms (the model) or restricting the edition of a document to only a few key fields, and then cross-referencing the inputted data all over the document would do the trick... but I still feel that I could de-couple both layers a bit more.
UML modeling - Using CASE tools with UML support, I thought I could model my documents as packages and classes with annotations, change the model for each project and generate a report using a document template. The problem is that those tools are not designed for treating large chunks of text and I am having some difficulties to progress.
Process modeling - Using Eclipse EPF https://www.eclipse.org/epf/ seems a bit overkilling for what I want to accomplish. Remember: I´m a lazy person.
I would like to ask the community on their experiences with model-based documentation or their ways to optimize the generation of documents throughout the software development cycle.
I'm not sure I fully understand, so apologies if this misses the mark.
I've faced (I think) a similar problem, where there's a many:many relationship between content and the documents it needs to be presented in. For example, a 'project overview' that needs to be included in a requirements document, project plan, etc.
Thus far the best solution I've found is:
Write each section in Markdown format. There are some nice editors that make writing Markdown easy and efficient (e.g. Mou on OSX).
Use Pandoc to convert Markdown into Restructured Text (RST).
Use Sphinx to generate documents from the RST files.
I have multiple Sphinx doc templates, each of which combines some of the common sections with others specific to that doc. If one of the common sections gets updated it's easy to re-generate all docs to incorporate. Version Control is pretty straightforward as the source files are all simple text. Sphinx can also generate multiple formats easily: for example html to put online, or pdf for printing/distribution.
You could remove the need for step 2 by writing in RST natively. For me the extra step is worth it as I haven't found an RST editor that's as comfortable or efficient as Mou. YMMV of course.
It's not a perfect solution: for example, creating links across sections isn't that easy. But in general it works well for my needs.
hth.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I have had contact with Google Chromium Code and that’s terrific for building applications with. The problem now lies that no-one has tried to use it outside Google Chromium Project. What I have in mind is to develop an open source project which may be used for this purpose. The fundamental goals would be:
Guarantee Linux-Windows support for the same code.
Take advantage of all resources available like thread control, stats, unit test…
Make it clearer how to use Skia for graphic effects and customizations.
Present a useful application doing the most of this.
Integrate C++ and JavaScript code using V8
Use Webkit for rendering html content
There’s a chance of it get off the paper. What do YOU think?
Claudio M. Souza Junior
Developer.
see https://github.com/lianliuwei/chromium_base
I create it for the same reason like you.
chromium is great project. It's code could be useful to using in other project. but It need time to extract it. I see one project to extract the ui part, but it change too many for noreason for example it change the .cc to .cpp. my project extract the base, ui, view part for the origin project, rm the ICU (it's so big) and gurl(you can add it quick) keep the gyp, gclient, grit-i18n, gtest, gmock... change the code little. and keep the extract history. I add a new type of messageloop for using it in the MFC(for company project :( ) now it can only work on Windows but it's no so hard to make it work on linux.(google do it all)
for use the browser in you project you can see the http://code.google.com/p/chromium/ for help.
It's great this project help you a litte. I at first think it's a no one care project.
I'm assuming you have looked at the extensively documented and developed QtWebkit and know why you don't want to use that?
I'm sure it will be easier to use V8 in a QtWebkit application than to somehow tear out Chromium's "View project".
Qt has the bonus that as long as you operate within the framework, everything will work on a lot of different platforms (more than Chomium now supports I think).
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 4 years ago.
Improve this question
Is there a web service API that takes this type of a latex http-request:
http://some_web_service/texfile?texfile=
\new\documentclass[12pt]{article}
\begin{document}
bla
\end{document}
and returns:
bla.pdf
the Online LaTeX Equation Editor is perfect for this.
EG:
uses the following markup:
![equation using Online Equation Editor]
(https://latex.codecogs.com/gif.latex?x&space;=&space;\frac{4}{5}+\pi\Omega\int_{2\pi}^{\infty}{5\left\(\frac{\tau+3}{2}\right\)d\omega})
note that you will need to escape parentheses with a backslash, eg: \left\( stuff \right\)
If you look through the editor API documentation you might figure out that you can change the format from gif to png by changing the api url endpoint from /gif.latex to /png.latex.
There's also options to set a white background by using \bg_white:
![equation using Online Equation Editor]
(https://latex.codecogs.com/gif.latex?\bg_white&space;x&space;=&space;\frac{4}{5}+\pi\Omega\int_{2\pi}^{\infty}{5\left\(\frac{\tau+3}{2}\right\)d\omega})
See also this meta.stackexchange answer and this tex.stackexchange answer. I'm sure there are many more answers that point to this tool and implement it in different ways. IE: instead of using the url to generate a gif or png using markdown notation, or you could use html markup and bypass markdown or you could just drag the image over to your post.
I'm looking for the same thing and Latex Online seems to be the closest thing to what we need.
You just need to setup the server by yourself.
EDIT
I've written my own little Sinatra app for this: https://github.com/codegestalt/sinatratex
ScribTeX has a CLSI API, you can send CLSI requests from any platform to compile LaTeX.
I blogged some time ago about this along with a CLSI client written in F#.
The Common LaTeX Service Interface (CLSI) is a web service interface and implementation that exposes common LaTeX related capabilities (such as compiling LaTeX documents to different formats):
http://code.google.com/p/common-latex-service-interface/
(This interface is one of the ways that latexlab.org can compile latex)
Fundamentally, this shouldn't be any different than a build server like you see for lots of open source projects (along the lines of Koji for example). Ultimately, you would just hook into pdflatex instead of gcc.
Were you to be able to install software on your local server this wouldn't be too hard. Some combination of Perl / TT / latexmk along with a LaTeX system (e.g. TeXLive or MiKTeX).
I don't know about latexlab mentioned above. The closest thing I know of is http://www.tlhiv.org/ltxpreview/ , which perhaps you could wrap to do what you need (or even write a howto for your users).
Just for completeness:
GitHub or docker might do the trick.
It's basically a micro service implemented in java/spring boot, which is wrapping pdflatex. Urls are immutable and the pdfs are stored on disk/distributed storage. You'll have to host it on your own though. The code is pretty simple and you're able/allowed to customize it to your needs. See the "Scaling the service" section in readme for more details about setting up a production environment.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 10 years ago.
Improve this question
I have an unfinished MathML rendering library written in C++. I ceased development a few months ago due to lack of time. The library [still] uses the TrueType version (unsupported) of the STIX fonts beta [version 1.0 of the STIX fonts (OpenType Postscript format) has since been released].
Development of this kind of library is a HUGE undertaking and, in fact, requires a number of programmers/developers. In my case, I am doing it alone, and here's my question:
Does anyone of you know of any foundations/philanthropists who may be interested to fund my project in return for open sourcing the code?
The funding will serve as an incentive for me to finish the library - perhaps by taking a sabbatical :p - and, of course, as 'payment' for the intellectual property involved.
I've searched the web, contacted some [e.g., foundations, VCs, angels, etc.], but I either did not get a response (from VCs and angels) or was rejected (one reason is geography since these foundations support only US-based projects).
As an aside, when I search the web for MathML, the results are often outdated. I guess there's not much activity concerning MathML. Yet, I believe this library will be very useful not only to developers but also to anyone who uses math, especially students and teachers. It is useful for e-learning, can be used with desktop apps and web servers (Windows), makes it easy to insert images of formulas in PowerPoint documents, etc.
Any suggestions are most welcome. Thank you.
EDITS: I have finished this library finally without funding, although I don't rule out seeking one.
You can find my new site below with lots of sample formulas; click on the download link to download the SDK.
http://reformath.webnode.com/ (preferred for statistical reason)
http://reformath.weebly.com/ (please use the above link instead)
DON'T forget to provide some feedback - or donations. Thanks!!!!!
Since we've already got open source MathML (Firefox has had it for years) that mean you'd have to do something better than the existing OSS solutions. And at that point, why not work on an existing open source project?
So that leaves commercial apps that may want a closed library for MathML rendering. I would go after companies like the makers of MathCad, Matlab, or any other engineering software that may want to display equations neatly. You should have something that already works for some subset of the things you/they will want it to do. You should also turn yourself into a company before going to those places so they take you seriously and you can license it to multiple customers. Otherwise the most you're likely to get is a job offer where they'd like you to hand over what you've got (for free if they can get you to) and then work on it as an employee - which may be all you want if you love it and hate your day job ;-)
You should probably ask on www-math list, also if you ask there, we can list your application in the software implementations page
http://www.w3.org/Math/Software/
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I would like to generate documentation for a RESTful web service API that is written in Python. Ideally it would look like Yahoo's RESTful web service docs. Does anyone have any ideas or references?
The Sphinx project (www.sphinx-doc.org) is the current state-of-the-art in Python documentation. It's really powerful and flexible... so also somewhat confusing. Still, I think it is your best bet.
There is excellent documentation on their site on how to set up the document source files and the process of building them in to finished documentation such as HTML. The part that should interest you is its system of incorporating docstrings from Python source, which I'm assuming you've been doing for the methods that serve your REST requests. Note that this will NOT magically interpret what is going on, but will bring all the named elements and their arguments (if appropriate) and provide a good framework for you to put in the appropriate documentation.
Assuming you have all of your REST functionality in a module named restapi.py and it is simply in your src directory of your project, you need to do two things to get Sphinx to automatically generate the documentation:
First, include the autodoc extension and add the src directory to Sphinx's path in conf.py:
import sys, os
sys.path.append(os.path.abspath('sphinxext'))
extensions = ['sphinx.ext.autodoc']
sys.path.append(os.path.abspath('src'))
Then in the Sphinx
.. automodule:: restapi
:members:
Note: this information was taken straight from the Sphinx "First Steps" document with minimal reordering. Do have a look at that document and the rest of the site if this seems like it would serve your needs.
Unfortunately I don't know anything specific that will help you in Python specifically -- However just as points of reference, you might take a peak at the WADL specification that the JAX-RS java spec is using -- https://wadl.dev.java.net/ -- Additionally, there is a xslt that will transform the wadl into html -- http://www.mnot.net/webdesc/
They use the yahoo REST API's as examples.
It sounds like you're not making a REST API, but simply an RPC. There's generally no easy, automated way to assemble a REST API, which should primarily be a description of your media types.
If what you mean is that you want something to pull together all the URIs in your service and put them into an API document, that's not REST at all, due to all the coupling from URI to resources.