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 have a Python project in PyCharm and I'd like to automatically generate API documentation (in the form of HTML) from my Python code and docstrings.
According to this page, there are a number of tools that generate Python API documentation:
autosummary
autodoc
pdoc
PyDoc
pydoctor
Doxygen
The page additionally notes that the following tools "process documentation":
DocUtils
Sphinx
The PyCharm documentation says that DocUtils and Sphinx can be used to "produce the formatted API documentation". However, this seems to be incorrect, as their configuration indicates that those tools process only *.rst files, not *.py files.
My question is this: Can I use the DocUtils or Sphinx features of PyCharm to generate the API documentation?
Failing that, can I use any features of PyCharm to do this?
Failing that, are there any tools to do this that integrate well with PyCharm?
I also stumbled on this problem in short:
My question is this: Can I use the DocUtils or Sphinx features of PyCharm to generate the API documentation?
No. However, you can use PyCharm to quickly view documentation ctrl+Q and it will be nicely formatted with links,tables etc.
Failing that, can I use any features of PyCharm to do this?
Not really, PyCharm can only insert documentation stub for functions and methods but it cannot do an api discovery to automatically comment everything it also cannot create rst documents stub.
Failing that, are there any tools to do this that integrate well with PyCharm?
Yes :) sphinx-apidoc it is a tool that will automatically create rst documents from your code. There is also less known autoapi
You just point to the root directory and voila it can even include members without doc string. It really just create a simple rst document using automodule syntax. After that you can just run sphinx task from PyCharm and you have a documentation of your code you can even use a theme like sphinx_rtd_theme to make it look really nice.
Example:
sphinx-apidoc -o source/ ../
Assuming you created a doc folder inside you project, then cd doc and used sphinx-quickstart the above command goes up to parent directory to discover any source file and document them. The result is stored in <project>/doc/source folder. Among other files there will be a modules.rst pulling all auto generated files together.
Then in your index.rst you add a line in .. toctree:: ... source/modules
EDIT
Recently I found a new tool to which I quickly switched seeing how easy it is to use pdoc3
Related
Closed. This question needs details or clarity. It is not currently accepting answers.
Want to improve this question? Add details and clarify the problem by editing this post.
Closed 5 years ago.
Improve this question
In C/C++ we write a makefile for a project installation/execution. How do we create a makefile or equivalent for a python project?
If python is a scripting language and we don't need a makefile. How do we integrate a python project with multiple python files (.py files)?
There is another thread with a similar question
Call a function from another file in Python. But my question is different from the one asked in that thread. One solution of my question may be possible by calling a function from another file. But I wanted a better solution as described by the Simon.
Python is a scripting language this means that there is no compiling/recompiling is necessary and errors are reported when you run the script. This removes one of the greatest assets of using make.
Although you can use makefiles for replacing long commands in the command line or controlling dictionaries/files, it is unlikely you will really need this.
If you are using C/C++ in with your Python project then it is highly recommendable.
You mention intergrating. makefiles are unlikely to be the tools you want. You need to build a module at the very least.
Modules allow you to use functions from other python files as if they were in that file. You need to import them and that's pretty much it.
If you want to install on other PCs use setup.py script to create a package. This allows you to make your project installable and then the project can be used just like an extension to Python.
Python is not like C or C++. Just knowing where to find the files together is fine for Python and when they are turned into modules you will just have to import them once and you will be able to use the functions they provide
The c/c++ makefile is mainly used for compiling the project, which is not needed with python as it is a a script language (not compiled). What kind of operations do you require from your makefile? For package management you can read about pip (a common python package manager)
Arrange your project of several python files into a package.
Package can mean to put several files together for others to use your code by means of an import package, or actually to distribute your app for others to use.
For the first just create a folder with the py files in it, and an empty __init__.py inside that folder. For the first and the second scenario also read the documentation here, and maybe here too.
The best analog is a shell script that executes your file. It could include taking care of any complicated arguments, setting environmental variables if necessary. To include other .py files, you can probably just import them into your main python file. But if you have more advanced needs I would recommend a second question
So this is my situation:
I am writing Ansible playbooks and roles in a huge project directory. Currently my documentation is stored in .md files. But I want to use Ansible's documentation mechanism, so I looked into the sphinx documentation system. It seems pretty neat to me, so I installed it and got into the mechanisms.
But what I cant figure out: How does Ansible include the documentation that is located in the python modules into the sphinx documentation?
I am sorry to be not able to be more specific, but currently I am just scratching the surface I assume.
So here is what I want to achieve:
I have the typical roles directory
In it there are several roles
The files are mainly .yaml or .yml files
I at least want to include documentation from one file within these role directories
Ideally I want to pull documentation from several files within the directory
If too much is unclear please tell me and I will try to improve the question as I can't figure out for hours how to achieve this or even how to ask precisely.
Thanks in advance for every comment and answer!
Auto doc is only for Ansible modules, not playbooks.
If you want to document your playbooks, you are on your own.
There is a small project on github: ansible-docgen – it fetches a list of tasks into MD files and adds a couple of headers.
You can achive comparable result by calling ansible-playbook --list-tasks myplaybook.yml
In my personal opinion, reading playbooks with comments is very convenient.
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 8 years ago.
Improve this question
I am developing an API in Unix environment for virtual machines. Most of the modules are developed in python. I have few questions on this.
I have the file extension as abc.py . I would like to make this as a command. For example , "virtman dominfo [vmid]" should be the command syntax. Now I have to give "virtman.py dominfo [vmid]" to achieve this. So how can make this as a command?
I want to make this as an installable API, I mean to install through apt-get/ yum install. What are the steps I need to do to achieve this or some reference URL's would be helpful.
Inside the API I am using absolute path like '/root/virtman/manager/' . Consider running this API in any unix environment , how can I make this absolute path generic to any OS/machine. Or should I have to assume some location where the API will get installed and give that path everywhere?
I read lot of articles but I didn't get the clear picture,so any hints/suggestions would be helpful.
This seems like it's three questions in one, so I'll attempt to answer each in turn:
File Extensions
Python scripts don't need to have a .py extension in order to be run. For example:
#!/usr/bin/python
print("Hello, World!")
Save this as a file called hello and flag it as executable. You should be able to run it from a terminal window by entering ./hello
apt-get / yum
Different systems use different packaging systems. For example, Debian and derivatives such as Ubuntu use .deb files, while Red Hat and co. use .rpm instead (though Debian can load .rpm files via the "Alien" tool). Each is slightly different, so I can't really give you a "generic" answer - hopefully this should be enough to get you started: https://fedoraproject.org/wiki/How_to_create_an_RPM_package
Generic Paths
You should be okay if you stick to the usual /var, /etc, /tmp layout - see this Wikipedia page for details.
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
There're tons of apps/widgets for PHP function reference and even for Ruby but I'm shocked to find there is nothing available for a popular language like Python (besides the official online documentation ofcourse).
Is there really not a single handy reference widget/app available for Python? I have 'Pocket Reference' book, but a dashboard widget would be so handy!
Python libraries have (or should have) built in documentation through docstrings. Also, python code is (mostly) very readable, and reading the source (.py or even .c) is actually the preferred way for many developers to get the information they're looking for, especially since some corner cases may not even be documented.
I've caught myself looking through the source now and then, as if it's a natural step in looking up functionality, either because I'm curious how they solve the problem, or because I reckon it's faster than googling obscure problems and reading SO questions.
So it's (often) not very pretty at all, but it's possible that the pydoc command line tool, or pydoc in webserver mode, could help you here. Here's an article on pydoc to help you get started
The interactive interpreter is a fantastic reference tool. dir(<identifier) lists all the attributes of a module, class, or function help(<identifier>) gives you help about same.
pydoc at the command line is another great tool. It does for Python what man gives you for commands, plus it even includes a web server you can start up to see the documentation in your browser.
I develop on Mac OS.
I have all the Python documentation directly available through a desktop app.
The app is called Safari. I bookmark http://docs.python.org/index.html
It's available as a desktop app.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
Questions asking us to recommend or find a tool, library or favorite off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it.
Closed 9 years ago.
Improve this question
Do you know of any tool that could assist me in obfuscating python code?
Your problem space is underspecified. Is this for a command-line app? Is this code supposed to be used as a library?
In addition to the two other answers, you could embed the code into a binary. When it starts, decode the code and eval the string. This works for a shared library extension as well. You could also do that with byte code, I think, but it wouldn't be as simple as calling Py_EvalCode.
py2exe or freeze are other solution, which convert the code into an executable. It just includes the code in the binary, and doesn't do any sort of serious obsfucation, but it's still harder than opening a .py file.
You could write the code in Cython, which is similar to Python and writes Python extension files in C, for use as a .so. That's perhaps the hardest of these to reverse engineer and still give you a high-level language for develoment.
They are all hackable, as are all solutions. How hard to you want it to be?
http://www.lysator.liu.se/~astrand/projects/pyobfuscate/
Or at http://freshmeat.net/projects/pyobfuscate/
I actually found a very nice project which basically converts a Python to C++ and create a binary, statically linked file.
Check this out: http://www.nuitka.net/
In many situations you can ship byte-compiled .pyc files instead of the .py source files. This gives you some level of obfuscation. As the pyobfuscate README suggests, this has limitations. But you may be able to combine the two approaches.
Python's standard library includes compileall.py. You can run this on a directory and it will generate .pyc files for all your source files. The .pyc files will only include bytecode and docstrings, and will strip out all comments. You could then copy this directory, and then run something like rm -rf $(find . -name .py) to remove the original source files.
Your best bet is to compile it using Shed Skin, an experimental Python-to-C++ compiler.
Although it doesn't do obfuscation, this Python recipe works very well for minimizing the size of Python code, including stripping out comments.