jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Handle doxygen code command with language option

Browse source 
Previously, code blocks were always written to the pydoc output with
"code-block:: c++", and use of language options (e.g., \code{.py}) was
not supported.  Now the option provided to the doxygen code command is
checked, and several basic cases are handled (python, java, and c),
defaulting otherwise to C++ as before (handling for additional cases
can easily be added).
This commit is contained in:
John McFarland 2019-08-04 17:03:15 -05:00
commit 569ac5ec4f
2 changed files with 31 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Source/Doxygen/doxyparser.cxx
View file

@ -690,7 +690,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
// \f{ ... \f} // \f{ ... \f}
// \f{env}{ ... \f} // \f{env}{ ... \f}
// \f$ ... \f$ // \f$ ... \f$
else if (theCommand == "code" || theCommand == "verbatim" else if (getBaseCommand(theCommand) == "code" || theCommand == "verbatim"
|| theCommand == "dot" || theCommand == "msc" || theCommand == "f[" || theCommand == "f{" || theCommand == "f$") { || theCommand == "dot" || theCommand == "msc" || theCommand == "f[" || theCommand == "f{" || theCommand == "f$") {
if (!endCommands.size()) { if (!endCommands.size()) {
// fill in static table of end commands // fill in static table of end commands
@ -707,7 +707,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
if (it != endCommands.end()) if (it != endCommands.end())
endCommand = it->second; endCommand = it->second;
else else
endCommand = "end" + theCommand; endCommand = "end" + getBaseCommand(theCommand);
std::string content = getStringTilEndCommand(endCommand, tokList); std::string content = getStringTilEndCommand(endCommand, tokList);
aNewList.push_back(DoxygenEntity("plainstd::string", content)); aNewList.push_back(DoxygenEntity("plainstd::string", content));

37
Source/Doxygen/pydoc.cxx
View file

@ -186,12 +186,12 @@ static string padCodeAndVerbatimBlocks(const string &docString) {
// Helper function to extract the option value from a command, // Helper function to extract the option value from a command,
// e.g. param[in] -> in // e.g. param[in] -> in
static std::string getCommandOption(const std::string &command) { static std::string getCommandOption(const std::string &command, char openChar, char closeChar) {
string option; string option;
size_t opt_begin, opt_end; size_t opt_begin, opt_end;
opt_begin = command.find('['); opt_begin = command.find(openChar);
opt_end = command.find(']'); opt_end = command.find(closeChar);
if (opt_begin != string::npos && opt_end != string::npos) if (opt_begin != string::npos && opt_end != string::npos)
option = command.substr(opt_begin+1, opt_end-opt_begin-1); option = command.substr(opt_begin+1, opt_end-opt_begin-1);
@ -566,10 +566,31 @@ void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComme
// Use the current indent for the code-block line itself. // Use the current indent for the code-block line itself.
translatedComment += indent.getFirstLineIndent(); translatedComment += indent.getFirstLineIndent();
// Go out on a limb and assume that examples in the C or C++ sources use C++. // Check for an option given to the code command (e.g. code{.py}),
// In the worst case, we'll highlight C code using C++ syntax which is not a // and try to set the code-block language accordingly.
// big deal (TODO: handle Doxygen code command language argument). string option = getCommandOption(tag.typeOfEntity, '{', '}');
translatedComment += ".. code-block:: c++\n\n"; // Set up the language option to the code-block command, which can
// be any language supported by pygments:
string codeLanguage;
if (option == ".py")
// Other possibilities here are "default" or "python3". In Sphinx
// 2.1.2, basic syntax doesn't render quite the same in these as
// with "python", which for basic keywords seems to provide
// slightly richer formatting. Another option would be to leave
// the language empty, but testing with Sphinx 1.8.5 has produced
// an error "1 argument required".
codeLanguage = "python";
else if (option == ".java")
codeLanguage = "java";
else if (option == ".c")
codeLanguage = "c";
else
// If there is not a match, or if no option was given, go out on a
// limb and assume that the examples in the C or C++ sources use
// C++.
codeLanguage = "c++";
translatedComment += ".. code-block:: " + codeLanguage + "\n\n";
// Specify the level of extra indentation that will be used for // Specify the level of extra indentation that will be used for
// subsequent lines within the code block. Note that the correct // subsequent lines within the code block. Note that the correct
@ -671,7 +692,7 @@ void PyDocConverter::handleTagParam(DoxygenEntity &tag, std::string &translatedC
const std::string paramValue = getParamValue(paramName); const std::string paramValue = getParamValue(paramName);
// Get command option, e.g. "in", "out", or "in,out" // Get command option, e.g. "in", "out", or "in,out"
string commandOpt = getCommandOption(tag.typeOfEntity); string commandOpt = getCommandOption(tag.typeOfEntity, '[', ']');
if (commandOpt == "in,out") commandOpt = "in/out"; if (commandOpt == "in,out") commandOpt = "in/out";
// If provided, append the parameter direction to the type // If provided, append the parameter direction to the type