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.
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 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.
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 6 years ago.
Improve this question
OData is used by Netflix and in many of Microsoft's products (servers: CRM, Sharepoint, SQL Server; clients: Excel).
While OData is interesting, it has it's own set of benefits and trade-offs.
I've designed and build a custom search engine for internal use. Many developers are using the search engine for reporting and lists, replacing the reports and custom search/filter functionality in each line of business app with this search engine.
I have a decent system to allow querying/filtering in my search engine. It's all url driven so it's easy to use.
At this point, I want to add a little bit more functionality to the URL "command line". OData is a tempting choice because we use a lot of Microsoft tech already. It also has standard language for filters with Boolean logic, etc.
Are there any other legitimate standards based REST frameworks like OData that I should look at?
I'm not sure I need the full OData stack for what I'm doing. My simple query string based filtering is working very well at this point. Just want to conduct some due diligence so I can make an informed decision.
Thanks.
Edit
What I'm looking for is more of a framework for creating my search API. Lucene/Solr use a url syntax http://lucene.apache.org/solr/tutorial.html as does OData. Lucene/Solr aren't exactly what I'm looking for and are too complex for my scenario. However, they have a well defined url api.
I'm looking for any other well define url-based api examples. I want to see the "prior art" for defining a query/search syntax based on a url and query string parameters.
While some will certainly argue, rolling your own is certainly an option; provided you can release a consumable schema and syntax or API library. Given that you carefully research the current standards landscape and borrow from established (albeit unfitting) implementations, you (and supporters) could be inclined to produce a new or extended standard; perhaps one that solves an unsolved problem.
However, obligatory:
After some research it appears that no, there is not really a good alternative to OData at this point.
I'm saying this based on the features of Odata. Hopefully we'll see an alternative at some point.
Facebook is developing GraphQL. Data can be queried using JSON queries:
{
user(id: 3500401) {
id,
name,
isViewerFriend,
profilePicture(size: 50) {
uri,
width,
height
}
}
}
At the moment it is not usable. According to the Changelog they plan to release it as a kind of specification.
Here is another whitepaper
Google is pushing for GData, which seems feature crippled.
If you are looking for a web compliant search mechanism, I suggest looking at Open Search
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 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 6 years ago.
Improve this question
Most REST interfaces I see are described with a simple web page describing the URL, the method, accepted input and returned result. For example the Amazon S3 or the Twitter API documentation.
Human readable is apparently good enough for Amazon or Twitter. However are there any companies describing a REST API in a machine readable format? And if yes, which ones?
WSDL 2.0 claims is capable of describing REST. WADL is explicitly created for describing REST services. Both WSDL 2.0 and WADL seem to have a rather small following atm and it seem to be little return for the effort of creating and maintaining the description documents. By identifying real life examples it is basically possible to validate or negate this assumption.
Do you use WSDL/WADL to describe your services? Do you rely on WSDL/WADL to consume others' services? Does your tool of choice support either one at the moment? Are there any examples of broadly used REST services that can be used that are detailed in a machine readable format?
Yes, you should. You will be able to generate your client code, tests and documentation using a set of tools supporting WADL. Some examples can be found here. Also, I think you should stick with WADL, rather than WSDL 2.0 because it is less verbose and way simpler (IMHO). In fact, in WADL you describe exactly what the user sees on the documentation page, just using WADL XML syntax. BTW, that is why it's so easy to write XSLT-based documentation generators for WADL.
The following is just my personal opinion:
I think WADL is similar to site maps for html pages. Site maps are considered theoretically a good practice, but rarely implemented and even more rarely used by people.
I think the reason is simple - wandering around a site and pushing strategically placed buttons is often significantly more rewarding than browsing a complex map.
REST API methods should not require a formal description. So if API is created thoughtfully it is pretty easy to discover all the resources just by following strategically placed uri links of a 'home' RESTful resource.
There's a chicken/egg phenonenon here. WADL is useless without tools that produce or consume it. The tools are useless unless sites publish WADL. etc.
For me, The Amazon model works fine. Depending on your audience you will get more return on an effort to produce samples, including snips od sample dialogs (what does request1 look like on the wire, same for response 1, then request 2, response 2, etc), and code in vvarious languages that are important to you. If you want to go to a machine-readable definition, you can use XSD if it is an XML message format. Obviously this is not WADL but coupled with your english description, it may provide a little extra utility for developers.
What is the benefit of a machine-readable REST API definition?
The point of REST is for the API to be relatively simple and easy-to-understand. Natural language works well for this.
If you mean "API Type Definitions" when you say "API Definition" then there may be some value in providing metadata. This, however, is only one piece of an API definition.
Having "machine readable" API can easily repeat the API source code, violating the DRY principle.
It's often simpler to write English descriptions of what the REST verbs do and what the URI's are. Send the type's which are marshalled through JSON (or YAML or JAXB) as source code. That's the perfect machine-readable API -- actual working source for the message object class.
The most popular usage of WSDL (and WADL in the same way) is code generation. It sure helps speed up development, but nothing can replace plain old documentation. For humans and not for machines.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
What is the difference between Django and Joomla?
Or better still what is the difference between CMSs (Joomla, Drupal, etc) and Web Frameworks (Django, Symphony, Zend, etc)?
Using toy construction kit analogy-
CMS: Comparable to a doll house kit. You can customize it quite a bit, but it's well suited for building mainly one kind of toy.
Web Application Framework: Comparable to a Lego set. you can build various kind of toy structures rapidly as you don't need to make the left bricks yourself.
no Framework: Developing web apps only with a programming language's standard library is like making toys out of plain clay. It offers most freedom, but you also pay the price of making all the pieces yourself.
Django (and web frameworks) provide common functionality needed to build most common websites. This functionality is mostly technical and a novice user (read: non programmer) has little knowledge on how to utilize it.
Where as Joomla (and CMSes in general) are packages aimed at non programmers (but still technical users, somewhat at least) to deploy and run websites using them.
If you install Joomla, you can add content to your website
If you install Django, you can start programming something that will allow you to add content
Straight off the Django website:
Is Django a content-management-system (CMS)?
No, Django is not a CMS, or any sort of “turnkey product” in and of itself. It’s a Web framework; it’s a programming tool that lets you build Web sites.
For example, it doesn’t make much sense to compare Django to something like Drupal, because Django is something you use to create things like Drupal.
Of course, Django’s automatic admin site is fantastic and timesaving – but the admin site is one module of Django the framework. Furthermore, although Django has special conveniences for building “CMS-y” apps, that doesn’t mean it’s not just as appropriate for building “non-CMS-y” apps (whatever that means!).
Web frameworks are programmer tools that help build content managers and similar web applications.
Just as content managers can be categorized from simple & easy (Wordpress? and Joomla?) to highly customizable & complex (Typo3?), frameworks can be best for certain tasks (and not so graceful at others). Some web frameworks (Rails?, Django? and TurboGears?) are more geared towards CMS-like applications, some others (Werkzeug? and Twisted?) try to provide foundation for more complex applications. And there are others (Pylons?) trying to find the middleground.
NOTE: Project names in parenthesis all have a question mark because the categorization is my personal opinion. They may or may not be correct examples.