PY-17333 Don't allow Docutils to parse indented first line specially
[idea/community.git] / python / src / com / jetbrains / python / documentation / docstrings / PyStructuredDocstringFormatter.java
1 /*
2  * Copyright 2000-2014 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.jetbrains.python.documentation.docstrings;
17
18 import com.google.common.collect.Lists;
19 import com.intellij.execution.configurations.GeneralCommandLine;
20 import com.intellij.execution.process.ProcessOutput;
21 import com.intellij.openapi.diagnostic.Logger;
22 import com.intellij.openapi.module.Module;
23 import com.intellij.openapi.module.ModuleManager;
24 import com.intellij.openapi.module.ModuleUtilCore;
25 import com.intellij.openapi.projectRoots.Sdk;
26 import com.intellij.openapi.vfs.encoding.EncodingProjectManager;
27 import com.intellij.psi.PsiElement;
28 import com.jetbrains.python.HelperPackage;
29 import com.jetbrains.python.PythonHelper;
30 import com.jetbrains.python.psi.PyIndentUtil;
31 import com.jetbrains.python.psi.StructuredDocString;
32 import com.jetbrains.python.sdk.PySdkUtil;
33 import com.jetbrains.python.sdk.PythonEnvUtil;
34 import com.jetbrains.python.sdk.PythonSdkType;
35 import com.jetbrains.python.toolbox.Substring;
36 import org.jetbrains.annotations.NotNull;
37 import org.jetbrains.annotations.Nullable;
38
39 import java.io.File;
40 import java.nio.ByteBuffer;
41 import java.nio.charset.Charset;
42 import java.util.ArrayList;
43 import java.util.HashMap;
44 import java.util.List;
45 import java.util.Map;
46
47 /**
48  * @author yole
49  */
50 public class PyStructuredDocstringFormatter {
51   private static final Logger LOG = Logger.getInstance(PyStructuredDocstringFormatter.class);
52
53   private PyStructuredDocstringFormatter() {
54   }
55
56   @Nullable
57   public static List<String> formatDocstring(@NotNull final PsiElement element, @NotNull final String docstring) {
58     Module module = ModuleUtilCore.findModuleForPsiElement(element);
59     if (module == null) {
60       final Module[] modules = ModuleManager.getInstance(element.getProject()).getModules();
61       if (modules.length == 0) return Lists.newArrayList();
62       module = modules[0];
63     }
64     if (module == null) return Lists.newArrayList();
65     final List<String> result = new ArrayList<String>();
66
67     final String preparedDocstring = PyIndentUtil.removeCommonIndent(docstring, true).trim();
68
69     final HelperPackage formatter;
70     final StructuredDocString structuredDocString;
71     final DocStringFormat format = DocStringUtil.guessDocStringFormat(preparedDocstring, element);
72     if (format == DocStringFormat.GOOGLE) {
73       formatter = PythonHelper.GOOGLE_FORMATTER;
74       structuredDocString = DocStringUtil.parseDocString(DocStringFormat.GOOGLE, preparedDocstring);
75     }
76     else if (format == DocStringFormat.NUMPY) {
77       formatter = PythonHelper.NUMPY_FORMATTER;
78       structuredDocString = DocStringUtil.parseDocString(DocStringFormat.NUMPY, preparedDocstring);
79     }
80     else if (format == DocStringFormat.EPYTEXT) {
81       formatter = PythonHelper.EPYDOC_FORMATTER;
82       structuredDocString = DocStringUtil.parseDocString(DocStringFormat.EPYTEXT, preparedDocstring);
83       result.add(formatStructuredDocString(structuredDocString));
84     }
85     else if (format == DocStringFormat.REST) {
86       formatter = PythonHelper.REST_FORMATTER;
87       structuredDocString = DocStringUtil.parseDocString(DocStringFormat.REST, preparedDocstring);
88     }
89
90     else {
91       return null;
92     }
93
94     final String output = runExternalTool(module, formatter, preparedDocstring);
95     if (output != null) {
96       result.add(0, output);
97     }
98     else {
99       result.add(0, structuredDocString.getDescription());
100     }
101
102     return result;
103   }
104
105   @Nullable
106   private static String runExternalTool(@NotNull final Module module,
107                                         @NotNull final HelperPackage formatter,
108                                         @NotNull final String docstring) {
109     final Sdk sdk = PythonSdkType.findPython2Sdk(module);
110     if (sdk == null) return null;
111
112     final String sdkHome = sdk.getHomePath();
113     if (sdkHome == null) return null;
114
115     final Charset charset = EncodingProjectManager.getInstance(module.getProject()).getDefaultCharset();
116
117     final ByteBuffer encoded = charset.encode(docstring);
118     final byte[] data = new byte[encoded.limit()];
119     encoded.get(data);
120
121     final Map<String, String> env = new HashMap<String, String>();
122     PythonEnvUtil.setPythonDontWriteBytecode(env);
123
124     final GeneralCommandLine commandLine = formatter.newCommandLine(sdkHome, Lists.<String>newArrayList());
125     LOG.debug("Command for launching docstring formatter: " + commandLine.getCommandLineString());
126     
127     final ProcessOutput output = PySdkUtil.getProcessOutput(commandLine, new File(sdkHome).getParent(), env, 5000, data, true);
128     if (!output.checkSuccess(LOG)) {
129       return null;
130     }
131     return output.getStdout();
132   }
133
134   private static String formatStructuredDocString(@NotNull final StructuredDocString docString) {
135     final StringBuilder result = new StringBuilder();
136
137     final String attributeDescription = docString.getAttributeDescription();
138     if (attributeDescription != null) {
139       result.append(attributeDescription);
140       final String attrType = docString.getParamType(null);
141       if (attrType != null) {
142         result.append(" <i>Type: ").append(attrType).append("</i>");
143       }
144     }
145
146     formatParameterDescriptions(docString, result, false);
147     formatParameterDescriptions(docString, result, true);
148
149     final String returnDescription = docString.getReturnDescription();
150     final String returnType = docString.getReturnType();
151     if (returnDescription != null || returnType != null) {
152       result.append("<br><b>Return value:</b><br>");
153       if (returnDescription != null) {
154         result.append(returnDescription);
155       }
156       if (returnType != null) {
157         result.append(" <i>Type: ").append(returnType).append("</i>");
158       }
159     }
160
161     final List<String> raisedException = docString.getRaisedExceptions();
162     if (raisedException.size() > 0) {
163       result.append("<br><b>Raises:</b><br>");
164       for (String s : raisedException) {
165         result.append("<b>").append(s).append("</b> - ").append(docString.getRaisedExceptionDescription(s)).append("<br>");
166       }
167     }
168
169     if (docString instanceof TagBasedDocString) {
170       final TagBasedDocString taggedDocString = (TagBasedDocString)docString;
171       final List<String> additionalTags = taggedDocString.getAdditionalTags();
172       if (!additionalTags.isEmpty()) {
173         result.append("<br/><br/><b>Additional:</b><br/>");
174         result.append("<table>");
175         for (String tagName : additionalTags) {
176           final List<Substring> args = taggedDocString.getTagArguments(tagName);
177           for (Substring arg : args) {
178             final String s = arg.toString();
179             result.append("<tr><td align=\"right\"><b>").append(tagName);
180             result.append(" ").append(s).append(":</b>");
181             result.append("</td><td>").append(taggedDocString.getTagValue(tagName, s)).append("</td></tr>");
182           }
183           result.append("</table>");
184         }
185       }
186     }
187     return result.toString();
188   }
189
190   private static void formatParameterDescriptions(@NotNull final StructuredDocString docString,
191                                                   @NotNull final StringBuilder result,
192                                                   boolean keyword) {
193     final List<String> parameters = keyword ? docString.getKeywordArguments() : docString.getParameters();
194     if (parameters.size() > 0) {
195       result.append("<br><b>").append(keyword ? "Keyword arguments:" : "Parameters").append("</b><br>");
196       for (String parameter : parameters) {
197         final String description = keyword ? docString.getKeywordArgumentDescription(parameter) : docString.getParamDescription(parameter);
198         result.append("<b>");
199         result.append(parameter);
200         result.append("</b>: ");
201         if (description != null) {
202           result.append(description);
203         }
204         final String paramType = docString.getParamType(parameter);
205         if (paramType != null) {
206           result.append(" <i>Type: ").append(paramType).append("</i>");
207         }
208         result.append("<br>");
209       }
210     }
211   }
212 }