Pycharm python integrated tools

Generate reference documentation

PyCharm helps produce the formatted API documentation, using the following documentation generators:

• The documentation generators should be properly installed on your machine. Refer to their respective download and installation pages for details.
• PyCharm recognizes the docstring format and uses the documentation source directory defined in the Python Integrated Tools page of the Settings dialog.

Generating Reference Documentation Using DocUtils

To generate docutils documentation

1. Select DocUtil task run/debug configuration, and change it as required: specify the configuration name, input and output directories, and optional keys.
2. Launch this run/debug configuration, as described in the section Run and rerun applications.

Generating Reference Documentation Using Sphinx

To create initial infrastructure for Sphinx documentation

1. Ensure that the Sphinx package has been installed with the Python interpreter ( Settings | Project | Python Interpreter ). Refer to Install, uninstall, and upgrade packages for more information about how to install a package in PyCharm.
2. From the main menu, choose Tools | Sphinx quickstart .
3. If the Sphinx working directory is not specified in the Python Integrated Tools page, the Set working directory dialog box opens, suggesting to specify the path to the documentation. If the Sphinx working directory is specified in your project, this dialog will not appear.
4. In the console that opens in PyCharm, answer the questions provided by the sphinx-quickstart utility. In particular, specify the source directory, where the generated conf.py file will be stored. If, answering this question, you just press Enter , PyCharm will use either the path you’ve specified in the previous step, or the path specified in the Sphinx working directory field of the Python Integrated Tools page.

The sphinx-quickstart utility is performed only once for a particular directory. If you want to generate the Sphinx infrastructure in a different directory, specify it in the Sphinx working directory field of the Python Integrated Tools page.

To generate Sphinx documentation

1. Open the Run/Debug Configuration dialog in one of the following ways:
   • Select Run | Edit Configurations from the main menu.
   • With the Navigation bar visible ( View | Appearance | Navigation Bar ), choose Edit Configurations from the run/debug configuration selector.
   • Press Alt+Shift+F10 and then press 0 .
2. In the Run/Debug Configuration dialog, click on the toolbar or press Alt+Insert . The list shows the run/debug configuration templates.
3. Select Sphinx task run/debug configuration, and change it as required: specify the configuration name, input and output directories.
4. Launch this run/debug configuration, as described in the section Run and rerun applications.

Источник

Python Integrated Tools

Use this page to configure requirements management file, default test runner, and documentation strings treatment.

Package requirements file

Type the name of the requirements file , or click the browse button, and select the desired requirements file from file system using the Select Path dialog.

Path to Pipenv executable

This path is required for adding a Pipenv environment to the Python project. The path can be autodetected by the system if added to the PATH environmental variable. To discover the path, follow the OS-specific pipenv installation procedure. Examples:

• C:\Users\jetbrains\AppData\Roaming\Python\Python37\Scripts\pipenv.exe (Windows)
• /Users/jetbrains/.loca/bin/pipenv (macOS)

Select the test run/debug configuration that PyCharm will suggest every time you choose Run on the context menu of a test case.

Select the format of the documentation strings to be recognized by PyCharm.

Depending on the selected docstring format, PyCharm will generate the stub documentation comments and render text in the show quick documentation:

• Plain : on pressing Enter or Space after opening quotes, an empty stub is generated; quick documentation shows as plain text.
• reStructuredText : on pressing Enter or Space after opening quotes, stub doc comment is generated according to reStructuredText format; the quick documentation is rendered by Docutils.
• Epytext : on pressing Enter or Space after opening quotes, stub doc comment is generated according to the epytext format; quick documentation is rendered by epydoc.
• NumPy : on pressing Enter or Space after opening quotes, stub doc comment is generated according to the NumPy format; the quick documentation is rendered by Napoleon and Docutils.
• Google : on pressing Enter or Space after opening quotes, stub doc comment is generated according to Google format; the quick documentation is rendered by Napoleon and Docutils.

All types of docstrings feature:

• Proper generation of docstrings
• Updates after applying intention actions and quick-fixes
• Coding assistance
• Autocompletion for section headers

Note that the information provided in the docstrings, is used for code insight.

Analyze Python code in docstrings

If this checkbox is selected, PyCharm highlights the code examples and performs syntax checks and code inspections.

If this checkbox is not selected, the code fragments inside docstrings are not analyzed.

Render external documentation for stdlib .

Enables showing documentation for standard library functions from http://docs.python.org in View | Quick Documentation .

Specify here the path to the directory that contains .rst files.

For recognizing custom roles, point to the directory with conf.py .

Treat .txt files as reStructuredText

If this checkbox is selected, the files with .txt extension will be highlighted same way, as the files with .rst extension.

Источник

Create documentation comments

Creating documentation comments for Python functions

To create documentation comment for a Python function

1. Place the caret after the declaration of a function you want to document.
2. Type opening triple quotes, and press Enter , or Space .
3. Add meaningful description of parameters and return values.

• Generation of docstrings on pressing Space after typing opening triple quotes only works when the checkbox Insert pair quote is cleared in the page Smart Keys of the editor settings.
• If you rename a parameter of a function, PyCharm will correspondingly update the tag in documentation comment.

To create documentation comment for a Python function using intention action

1. Place the caret somewhere within the function you want to document.
2. Press Alt+Enter to show the available intention actions.
3. Choose Insert documentation string stub : PyCharm generates documentation comment stub according to docstring format, selected in the Python Integrated Tools page.

Example of a Python documentation comment

Consider the following function:

Open settings Control+Alt+S and navigate to Tools | Python Integrated Tools .

In the Docstring format dropdown, select Epytext :

Then type the opening triple double-quotes and press Enter or Space . PyCharm generates a documentation comment stub in Epytext format:

Go back to the Python Integrated Tools page in settings ( Control+Alt+S ) and switch Docstring format to reStructuredText . Then type the opening triple double-quotes and press Enter or Space . PyCharm generates a documentation comment stub in reStructuredText format:

You can use markup for text formatting, as well as substitutions, bulleted lists, links, code blocks, and tables:

Источник

Project Setup

Make a PyCharm project and virtual environment with dependencies, then configure PyCharm to use pytest.

Python has projects and PyCharm does as well. In this tutorial step, let’s make both, with a virtual environment, and set the project up to use pytest .

New Project

We’ll let the IDE guide us through the process. First, we use File -> New Project to make a new project, in a directory:

Make sure Project Interpreter is setup to configure a new virtual environment. Expand the triangle if needed to set this up.

After clicking Create , tell PyCharm to open the project in a new window.

Python Project

Python packaging is, alas, a thorny topic, and we’re going to make you do it for this tutorial.

Most Python packages put their tests outside of their source directories, to avoid accidentally shipping the tests (among other reasons.) The tests thus need to import the package that you code is in, and that means a Python package. Fortunately this is all explained quite well in the pytest docs.

We first need a setup.py file at the top of our new project. Add the following:

from setuptools import find_packages, setup

setup( 
name='laxleague', 
extras_require=dict(tests=['pytest']), 
packages=find_packages(where="src"), 
package_dir="": "src">,
) 

Our source will now go in a src/laxleague directory so make sure to create it.

Why the use of src ? It’s a general consensus best practice that avoids nasty surprises if you share your code or use it elsewhere. Our setup.py has the packages and packages_dir keys added in support of putting our code under src .

Now go to PyCharm’s Terminal tool and type in the following:

• It makes this project an «editable install» by creating a directory named src/laxleague.egg-info
• pytest is installed into the project’s virtual environment

Apologies for this setup.py hocus-pocus. Python has a sordid history on this, though it is getting better.

Give Me Some Source

But we don’t have any source code yet. Let’s put a file at src/laxleague/player.py containing an empty Player class:

Configure Testing

One last step. we need to tell PyCharm to use pytest for its built-in Python testing support. This happens automatically when we first open an existing project with pytest in the virtual environment. We added pytest after making the environment, so we need to configure it ourselves.

Go to Settings -> Tools -> Python Integrated Tools and change Default test runner: to pytest :

Mine is set automatically because I set pytest as my default test runner for all projects using File | New Projects Settings | Settings/Preferences for New Projects :

Finally, make a top-level directory called tests . This mimics the pytest good practices.

When done, your directory structure should look like this:

Источник