I use Sphinx and the autodocs feature to ensure we have good docs in our project.
So I'm familiar with info field lists and I'm familiar with using cross-referencing in our docs.
However, when writing docstring for a method or function I find it useful to refer to their parameters in the text. But there doesn't seem to be a structured way to do this.
We could say e.g.
Use ``name`` to set the username
but that has no structure, requires you to remember what style you used for that and if you change style you have to hunt down and kill all the incorrect styles.
:param: doesn't work outside of a info field list so you can't write
Use :param:`name` to set the username
I've seen some projects use :parm: but that isn't documented and doesn't seem to work. So they must have some customisation
I could use generic_roles but that seems like me working around a problem that I'm sure others have encountered.
So hopefully I've just missed something blindingly obvious.
You can write your own extension using autodoc-process-docstring - it's really simple.
Have the extension search for :param: and replace it with your choice of style.
Related
I'm new to python and I'm comming from the c# world.
Over there it seemed like the repository pattern was the way to go, but I am having trouble finding any tutorials of how to best do this on Python.
edit I understand that it can be implemented, I'm just wondering if there is any reason why I am finding close to nothing for how to go about doing this.
Thanks!
I wasn't immediately familiar with the "repository pattern", so I looked it up. It appears to be the idea of putting a more general API, like a dictionary-like key/value lookup, in front of a database or other data store. It seems that the idea is to add an additional layer of abstraction that can allow multiple types of data sources (like both a relational database and a CVS file) to be accessed transparently via a common API.
Given this definition, I can think of no reason why this design pattern wouldn't be equally applicable to a problem addressed with Python vs any other programming language.
I'm creating a Django website for game developers to share code, which means I need to be able to save properly formatted code to a database, as well as being able to retrieve and display it.
Is there anything built into Django for this, or do I need to use a third party library?
I've played with a Django pagedown widget, which is modeled after StackOverflow's markdown editor, but I've had some trouble with it, and I'm not positive if that's is going to accomplish everything I want by itself.
Has anyone actually used the pagedown widget, implemented functionality similar to this, or know of another library that would work?
For storing the code, you can use any database that supports text types. That is, you would use a TextField in your model.
Now you need to decide how that raw text will be displayed/formatted.
This depends on what you mean by displaying properly formatted code, but I'm going to go ahead and just say you should check out Pygments. It is a syntax highlighting library that can be easily used w/Django.
Pygments works by your specifying a lexer (read: language) for it to apply styling to the target text. Whitespace will be preserved by your database. Everything else formatting-related is purely subjective. You'd presumably specify a fixed width font, a size, etc in the view and pass it to the context as you would any other DB-backed object.
Django Rest Framework's tutorial actually makes something very similar to what you are describing and uses Pygments, so I'd recommend checking that out for concrete usage examples.
For formatting code exclusively, I would avoid any markdown flavors like the one you listed, as code could contain characters that have special meaning in markdown, thus you would need to escape the text, and that defeats the purpose of markdown.
I have a Pyramid application with Cornice package where I defined Resources (rather than Services) and I wonder if it is possible to generate Sphinx documentation for this project with a help of Cornice's Sphinx integration?
I managed to generate some sort of documentation but it seems like majority of features are not available for Resources, only for Services, for example, documenting Pyramid code in this way:
#resource(collection_path='/parse/', path='/parse/{id}', cors_origins=('*',), description="Temporary description.")
class Parser(object):
#view(renderer='json')
def collection_post(self):
"""
Some description for this function...
:param str smth: Some parameter
:return: Returns something
"""
return
and building Sphinx documentation like this:
.. cornice-autodoc::
:modules: my_app.views.views_parser
:ignore: parser
will result in few unnecessary and few missing parts in documentation:
service names (actually resource names) are messed up,
function collection_post itself is not documented,
no need to document both collection_path and path from resource declaration):
(example snippet from generated documentation)
Collection_Parser service at /parse/
Temporary description.
POST
Response: json
Parser service at /parse/{id}
Temporary description.
What I would like to know is:
how to change names generated in documentation (Parser instead of Collection_Parser),
how to 'ignore' some modules with :ignore: statement (e.g. I don't want to document /parse/{id} part),
how to document functions within Resources, since putting a comment block is just being ignored (collection_post in my case)
...and many other things...
It seems like this is either impossible or not documented at all. If the case is that this is impossible is there any other (at least semi-automated) solution for documenting my project?
Seems like this is not possible because Cornice does not support this kind of functionality (https://github.com/mozilla-services/cornice/issues/279)...
I'm looking for a way to translate my Django project. Built in mechanism provided with Django is great, but has several weak points which made me go looking for an alternative.
Project owner must be able to edit every translation including English (original translation). With gettext it is possible to edit translations with tools like Pootle, but the original strings stay hardcoded inside file sources or templates. There is no way that product owner can change them.
Possible solution is to make gettext translate some unique identifiers, and just translate them to all languages including English, like this:
_('form_sumbit_button')
But this makes tools like pootle almost impossible to use for translators.
Question: are there any tools for Django project translation that could fit my needs?
If you use some message IDs, they would either be incomprehensible ("message_2215") or you'd be forced to synchronise the message IDs to the actual messages ("Please press any key" = "please_press_any_key" => "Any key to continue" = "any_key_to_continue"). Either way, real strings are better for the programmers and for the tools.
However, if you employ a separate proof-reader for your strings, you can do the following:
Create an English "translation" file (yes, this works)
Let your proof-reader "translate" from English to English using Pootle or any other tool
Make sure your programmers keep that translation file untranslated by updating the strings in code.
(optional) Create a way to deploy translations independently of your main code so you can fix a typo quickly.
You may be able to use Pootle with the _("message_id") approach, depending on how easy Pootle is to customise (I don't know the internals so I can't say, but IIUC it uses Django where template changes are usually straightforward).
For example, Pootle's translation screens have "Original" and "Translation" sections; you could perhaps adapt the templates to show, under the "Original" section, a "Reference" section which displays some canonical translation using a specific reference language (e.g. English).
Or you may be able to use Pootle's alternative source language functionality, without needing to customise Pootle. You could store the canonical versions of the translations using an unused language code (or a made-up one).
Using identifiers is definitely possible with Gettext and there are tools which support this. However it might be unusual for some translators as they are used to downloading only .po file for offline translation, what does not work with monolingual translations.
For example Weblate supports monolingual Gettext files just fine (I'm author of this tool): https://docs.weblate.org/en/latest/formats.html#monolingual-gettext
I'm going back over an old project where I added preprocessor functionality to Essence' and I realised that my previous solution of writing a domain specific language and associated lexer/parser was overkill.
Instead I just need to be able to embed dynamic language code into the file, isolate it at runtime, eval and insert the results. In other words very similar to the PHP model of inserting dynamic code into HTML. I'd rather not use PHP as Python is much easier to distribute as part of a larger project (IronPython or Jython)
So the question goes, how best to implement something like the following:
<code>Python goes here</code>
Lots of essence <code>Python</code> prime code goes here
I don't want to have to alter the structure of the Essence' file (if I remove all the code blocks everything left should be able to be syntactically correct. It needs to be able to insert text in place of a code block like PHP.
Finally security wise I'm not bothered about code injection, as it would be the user themselves choosing the file to execute although if there were security benefits to one model over another with no extra costs that would obviously be good.
Cheers in advance
Your best bet is to use one of the already made (and battle tested) Templating Engines. The two big ones that I've used are Mako, and Cheetah. They allow you to embed code right in the page, and are mostly used as the View in an MVC architecture.
If you feel that using one of those engines is overkill for your project, here is a small tutorial on how to implement basic templates yourself. Keep in mind that the example will need to be modified to suit your particular project/needs.