I have a Django website and I created a REST api. In the view functions I have documentation on the REST urls and I want to generate API docs for the REST urls. The view functions look like this:
def genres(request):
"""
Url: /api/genres/
Parameters: None
Returns: list of genres { { "id":1, "name":"action" }, {...} }
"""
pass
But when I run sphinx on myproject.api.views I get html docs for calling the api in python. Is there a way to configure sphinx to document it like a REST api?
Or am I better off writing a script to generate my docs from the docstrings myself?
Check sphinxcontrib-httpdomain
You can use autodoc in order to use the docstrings and the httpdomain extension in order to use .. http:get:: /users/ style directives. This solution has a problem, it will also show the functions' signatures. In order to get around the problem, I tinkered a bit with the Sphinx source code, making a copy of the original autodoc extension that wouldn't add the signatures to the final documentation.
The files can be found on https://gist.github.com/4589457
Instructions:
Replace application.py on sphinx path with the one on the gist (the path on my system is /Library/Frameworks/Python.framework/Versions/Current/lib/python2.7/site-packages/Sphinx-1.1.3-py2.7.egg/sphinx/)
Add simpleautodoc.py on the ext folder
Add the httpdomain extension on conf.py in order to use .. http:get:: /users/ style directives
Use simpleautodoc as you would use autodoc using the prefix autosimple instead of auto (eg autosimplemodule instead of automodule autosimpleclass instead of autoclass etc)
The example.py file shows a sample of how I format the docstrings
Related
I was using netflix's nebula. Looking here, I saw this line:
fileType [org.freecompany.redline.payload.Directive] - Default for types, e.g. CONFIG, DOC, NOREPLACE, LICENSE
I didn't find any doc about the actual meaning of this enum, but I've found the original code.
Now I want an actual description of this enum. I thought NOREPLACE is releated to being not allowed to replace the file. But I want to be sure and don't rely on assumptions.
I have only seen noreplace as an additional attribute on a config file, e.g. %config(noreplace). It means that if the user has edited the file, the installer should put its new version as filename.rpmnew; by default %config files are replaced with the user one put as filename.rpmold .
I use the current version of Gatsby (2.x) and want to use gatsby-image for rendering a gallery for products.
I have several YAML files for products. I can already create pages with the text content of these files but I also want to add a small gallery with images specified in the .yaml file.
An example YAML file looks like this:
product: "Some product"
description: "It is really awesome!"
screenshots:
- /img/product1/screenshot1.jpg
- /img/product1/screenshot2.jpg
- /img/product1/screenshot3.jpg
My problem now is that I can get the screenshots only as strings but I have no idea how to pass them to for rendering.
I thought of creating a component that takes the file name and uses a query to get the image data - but it can't take any parameters because it can only use static queries.
I've also not found a way to pass results from the first graphql query to a second for the image data.
If you install gatsby-transformer-sharp and gatsby-plugin-sharp and use a correct path to your images, Gatsby will automatically pick those up and pipe them through sharp, hence you can query those images. You can have a look at one of my sites which also uses a YML file with image paths that I then use with gatsby-image: https://github.com/LekoArts/gatsby-starter-portfolio/blob/master/src/sites/sites.yaml
I would like to write a generator plugin to add some post-like items to my blog. The items are supposed to appear in the blog index, but they have no page associated to them (you can't click on them).
I know I need something like
class QuoteGenerator < Generator
safe true
def generate(site)
# add a single post
site.posts << QuotePost.new(site, site.source, "Blub")
end
end
But what I don't understand is how to implement my Post subclass. I've found that other plugins (like this one to embed Flickr photos) write the data they want to a markdown+YAML file, and then reference this file:
class QuotePost < Post
def initialize(site, base, title)
# Nooo, I don't want to create a .md file for this
name = "2016-05-13-test.md"
dir = ""
# (write out .md file here)
super(site, base, dir, name)
end
end
But then, I would hardly need a Plugin in the first place. I could just generate the markdown files myself (with an external script).
What I'd like to do is to just set a couple of variables in my Post subclass, and have them available in the template for the blog index. How can I do that?
The case you've described looks to be unrelated to Post, since usual posts are file-based. Collections may be suitable, but again - that's not clear how you getting the content.
I'd suggest two major options:
Use _data/ to set an object list, where each item has the required properties if you can define them via a static JSON/CSV/etc file (or generate it once, to separate external data producer and jekyll visualization).
Use :pre_render hook and a plugin if you have to define the data via code -
your hook will also receive a payload hash as a second parameter which allows you full control over the variables that are available while rendering
Having your data in site.data variable allows you to iterate through items, render something or include a template and so on. Also there are plugins which generate new pages based on site's data.
The right answer depends on how you're getting the content, which markup you need and how those items will be used.
I would like to generate Rules DSL from the helper module. I have custom blog helper and i would like it to generate RSS feeds automatically so I don't have to specify any compile and routing rules in the Rules file as long as specific metadata is present.
So lets say I have my blog in news.erb and news\*.md directory. Erb file has blog configuration in its metadata section (number of articles to show, ordering etc..) In preprocessing I have create_blog function which generates \page\N depending on the metadata I have in news.erb. If this metadata includes rss: true section I would like the create_blog function to also register 2 aditional rules (if those are not previously defined) and 1 aditional file /feeds/news.xml:
compile /feeds\/.+/ do
filter :erb
end
route /feeds\/.+/ do
item.identifier.chop + '.xml'
end
I can generate the file all right, but in order to keep the site modularized I want to create those above rules in the create_blog itself. This allows me to later, if I want to remove the blog, just comment out the module and not change Rules file.
I use KendoUI library in my project, so it's already minified but incredibly big.
Is it possible to exclude it from being uglified when using grunt-usemin?
Thanks!
In your grunt configuration, use an explanation point to make an exclude. Place those at the end of your src array.
e.g., add to the end of the src array, add:
'!htdocs/js/kendo.all.min.js'
You'll have to modify your flow for js and use a custom post-processor, which basically consists on adding a flow property to your useminPrepare.options (follow the basic structure in usemin README file), but instead of just adding a step (e.g. 'uglify'), plug a custom post-processor:
name: 'uglify',
createConfig: function (context, block) {
...
}
To customize how it will handle files, copy the createConfig from the example file you find most useful (see files in grunt-usemin/lib/config/) and modify it as you need (i.e. excluding the file you want).
I used a custom post-processor to add ngAnnotate to the usemin flow for js, just changing name to ngAnnotate and copying the createConfig from uglify).