In PHP I was used to PHPdoc syntax:
/** Do something useful
#param first Primary data
#return int
#throws BadException
*/
function($first){ ...
— kinda short useful reference: very handy when all you need is just to recall 'what's that??', especially for 3rd-party libraries. Also, all IDEs can display this in popup hints.
It seems like there's no conventions in Python: just plain text. It describes things well, but it's too long to be a digest.
Ok, let it be. But in my applications I don't want to use piles of plaintext.
Are there any well-known conventions to follow? And how to document class attributes?! PyCharm IDE recipes are especially welcome :)
In Python3 there's a PEP 3107 for functional annotations. That's not useful for 2.x (2.6, specifically)
Also there's a PEP 0287 for reStructuredText: fancy but still not structured.
I use epydoc. It supports comments in reStructured Text, and it generates HTML documentation from those comments (akin to javadoc).
The numpydoc standard is well-defined, based around reStructuredText (which is standard within the python ecosystem), and has Sphinx integration. It should be relatively straight forward to write a plugin for PyCharm which can digest numpydoc.
Sphinx also has references on how to document attributes: http://sphinx.pocoo.org/ext/autodoc.html?highlight=autoattribute
Related
I am trying to understand what typ and pure=True mean in the ruamel.yaml Python library.
I've read the documentation here.
So far, I've understood that typ='safe' uses a safe loader which omits YAML tags parsing in YAML (they can lead to arbitrary code execution).
I haven't found any explanation about round-trip parser typ='rt' in the docs.
Also, I think explanation on pure=True is confusing:
Provide pure=True to enforce using the pure Python implementation (faster C libraries will be used when possible/available)
Are faster C libraries used with pure=True or not? If they do, why do you need to specify this flag in the first place?
There are four standard typ parameters:
rt: (for round-trip) in this case the document is loaded in special types that preserve comments, etc., used for dumping. This is what ruamel.yaml was created for and this is the default (i.e. what you get if you don't specify typ). This is a subclass of the safe loader/dumper.
safe: this only loads/dumps tagged objects, when these are explicitly registered with the loader/dumper
unsafe: try to load/dump everything. Classes are automatically resolved to a tag of the form !!python/object:<module>/<class>
base: the loader/dumper from which everything is derived. All scalars are loaded as strings (even the types like integer, float, Boolean that are handled specially as mentioned in the YAML specification or the type description
For safe, unsafe, base there is the faster C Loader available. If you install from the .tar.gz file these will only get compiled during installation when the appropriate compiler is available. If they are not available, because they could not be compiled, then they cannot be used.
There is no C version of the rt code. So it is not possible to use C libraries.
The word pure is for when you use Python only modules. The opposite would be "tainted": Python tainted with C extension modules. There is no tainted=True parameter. This is implicit (when possible/available, see previous paragraph) when pure=true is not specified, as the default for pure is False
In order to further confuse you: the above are the four basic (built-in) values for type. If you use plug-ins you can e.g. do
yaml = YAML(typ='jinja2')
as shown in this answer
Some of the above information is available from the YAML() docstring, little of that however made it into the package documentation, primarily as a result of lazyness of ruamel.yaml's author.
Stylus is a language that compiles into normal CSS. The language is a huge time- and space saver for many reasons. For instance, I can put selectors inside each other:
div.foo
color: red
div.bar
color: blue
font-weight: bold
div.baz
color: green
background-color: pink
I can also do stuff like make vendor-specific properties work without the prefixes, which saves a lot of space.
My question is: Are there any alternatives to Stylus? I can't really think of a description of what Stylus is, so I'm finding it hard to find any alternatives using Google.
Note: By alternatives, I mean languages that compile into CSS and offer time-saving goodies.
The reason I'm looking for alternatives is that I use Stylus for all my projects, and I want to see if there's a better solution out there. The reason I'm not 100% happy with Stylus is that the TextMate bundle for it is terrible, and Stylus requires Node.js to compile which is also a step I'd like to avoid. I use mainly Python.
Stylus' older siblings are LESS and Sass. I prefer Stylus to both, both because of features and speed, but they are pretty much interchangeable, AFAIK.
LESS is also written in javascript, and so will not release you from your node.js dependency. Sass is written in Ruby.
There is a Stylus implementation in Python. It's called Stilus and is nearing completion. You find it here: https://github.com/jw/stilus
CSS-On-Diet is written in Python. You can install it easily by
pip install CSSOnDiet
It saves a lot of time and space, but syntax is different
I can't really think of a description of what Stylus is
The term you are looking for is CSS preprocessor.
Check this ones:
Less: Unlike Stylus is a css super-set. In other words, every valid CSS document is also a valid Less document. This way is easier to migrate from existing CSS.
Sass: Very similar to Less. It has a variant (SCSS) which notation is also a SCC super-set. Some people prefer Sass over Less because his control-structures syntax (selection, iteration) is more natural for most programmers, since is very similar to the one used in most imperative programming languages (C++, Java, etc) while Less uses a recursive approach, more similar to functional programming languages.
Absurd JS: The styles are described by writting pure JavaScript code, given that his notation for objects literals is very similar to the CSS notation. This interesting approach allows you to manipulate and preprocess the styles in any form you can imagine, since you are no longer limited by a small bunch of control structures like in the two above, but you can use the whole toolset of features provided by a programming language. I strongly recommend this options if you are a programmer, or if as a designer you are interested in learning how to code, or if you want to describe and reuse your style definitions in a non-trivial or crazy way you can't achieve with just a preprocessor.
I didn't know Stylus before reading this question. It seems to be pretty nice. I like his Python-like approach of use line breaks and tabulations to define the structure of the code. I will give it a try. If you already use this preprocessor and you don't find any important drawback, I would stick with it.
Another way to ask this:
If I wrote doctests in reST, can I use it for Sphinx or other automatic documentation efforts?
Background: I don't know how to use Sphinx and have not much experience with reST either, so I am wondering if I can use reST-written doctests somewhere else useful than with Sphinx?
Why would I write doctests in restructured text?
You don't really write the tests "in restructured text". The interactive examples are the test cases, and it does not matter what the surrounding markup looks like; it could be reST, or it could be something else like Markdown or LaTeX.
reST has been adopted as the "official" markup language for Python documentation, but you are not obligated to use it.
so why is the simple usage example for doctest.testfile() from the doctest documentation then given as a reST file?
Doctest is a way to test code by checking the correctness of embedded interactive examples in documentation, so it makes sense that examples explaining the doctest module also include reST markup.
You can run doctest on text files that contain only interactive input/output examples, and no other content. Those examples could be useful as lightweight unit tests, but on their own they would be less suitable as documentation.
I am wondering if I can use reST-written doctests somewhere else useful than with Sphinx?
Having testable code examples can be useful even if you don't use Sphinx for your documentation.
If you are looking for alternative documentation tools that understand reST, take a look at docutils (which Sphinx is based on, btw) and its front-end tools, such as rst2html.py.
Another tool that might be of interest is rst2pdf.
Adding doctests to your documentation makes sense to ensure that code in your documentation is actually working as expected. So, you're testing your documentation. For general code-testing, using doctests can't be recommended at all.
I'm looking for a parser for Python (preferably v. 2.7) written in human-readable Python. Performance or flexibility are not important. The accuracy/correctness of the parsing and the clarity of the parser's code are far more important considerations here.
Searching online I've found a few parser generators that generate human-readable Python code, but I have not found the corresponding Python grammar to go with any of them (from what I could see, they all follow different grammar specification conventions). At any rate, even if I could find a suitable parser-generator/Python grammar combo, a readily available Python parser that fits my requirements (human-readable Python code) is naturally far more preferable.
Any suggestions?
Thanks!
PyPy is a Python implementation written entirely in Python. I am not an expert, but here's the link to their parser which - obviously - has been written in Python itself:
https://bitbucket.org/pypy/pypy/src/819faa2129a8/pypy/interpreter/pyparser
I think you should invest your effort in ast. An excerpt from the python docs.
The ast module helps Python applications to process trees of the
Python abstract syntax grammar. The abstract syntax itself might
change with each Python release; this module helps to find out
programmatically what the current grammar looks like.
I'd like to write notes for class in plain text.
I was wondering if there was a markup language for doing this, where I could parse the notes for key terms, titles, page #s etc programmatically with a language such as Ruby or Python.
In the Python world, reStructuredText is probably the most widely used markup language, and it's the result of a long-term and fairly rigorous design and development. It's the markup underlying the Sphinx documentation tool which, among other things, is used for the Python docs and many Python projects.
I also haven't seen a formal specification for other markup languages, at least not with the same thoroughness.
LYX! I used lyx all last semester and it was great. It takes a little while to get used to (like a week). By the end of the first week I was formatting equations and matrices just as fast as my classmates could write them down. The only problem is diagrams, but if you have a sheet of paper handy or even a tablet, it shouldn't be a problem at all.
http://www.lyx.org/
Note: Lyx is a tex parser that translates code in real time. You could also just use tex, but then you might not format things right. You could also use the openoffice tex plugin, but that doesn't work as well as LYX, but it does make life easier with the plain text formatting. Also, the openoffice plugin is not current.
here's a link to that project ooolatex:
http://ooolatex.sourceforge.net/