I contribute to a large code project that uses Doxygen to document a series of C libraries. We are also starting to use doxygen with doxypy for associated python modules.
Is there an easy way to document command-line programs (in python or C), and their command line options, (automatically) using doxygen?
In order to generate man pages, you need to set GENERATE_MAN tag to Yes (.doxyfile).
By default, a sub-folder named man is created within the directory provided using OUTPUT_DIRECTORY to contain the pages generated.
By doing that, doxygen will render all the markup you added to the source code as a man page (one page for each translation unit).
At this point, you might want to exclude certain parts you want to ignore (I assume you are interested in showing only how to call the main) using the exclude* directives.
I advise you to compile two different doxyfiles: one for internal usage (complete javadoc-like documentation), the other for producing the program man and the like.
Of course, you will not get the expected result at the first try and you might need to play with doxygen markup a bit.
Related
I am creating documentation for my project which has codes written in both C++ and Python. I can generate documentation with doxygen on my C++ codes, but find no way to do the same with my Python codes after I have the former files. And if I need both doxygen documents to appear under the same index.html, i.e. to merge them into one uniform doxygen file, how can I do this? What is the convention that everyone uses?
First off, thank you albert and shawnhcorey for your quick responses.
I tried what you suggested, and made the following modifications to parse documentation comments from files written in both languages:
In Doxyfile
INPUT = include/my_package/ scripts/my_package/
Both directories are separated by space.
Then,
FILE_PATTERNS = *.h *.py
The two wildcards patterns are also separated by a space.
Back to where you placed your doxyfile, then run
doxygen
And off you go!
Are there any particular modules in python which provide the generation of c file and write into this c file ? Currently I am parsing an xml file with python and I want to use the parsed information to create a desired data structure from the python script into a c file.
for example , i saw a reference from the link https://www.codeproject.com/Articles/571645/Really-simple-Cplusplus-code-generation-in-Python . Is there similar module for c code generation ??
By what you describe you just have to generate a source code file you will be using in your own project.
You just don t need any special Python library to do that.
The linked article you give does nothing special with the C++ strings for each line hardcoded into Python code, which linearly generates all the parts of the code: there is nothing special on that article about "creatign a C++" file - just put what you want in your final file in strings, and you can put your data values using the string format method, or the new f-strings.
However, if you want a nice and maintainable solution, you could use a template library for Python, like "jinja2". Once you have a jinja2 template for your desired C file, all you need to do is to call Jinja's render methods passing the custom data you want into the final file, and sabve the result to a file.
That is not specific about C, though, that is about creating a structered text file with data you have, and Jinja is a nice tool for that.
People are mentioning "Cython" around: Cython is a solution to convert Python-like code into C - that is, if you want a program you wrote in Python to become a C program. (Although it is seldon used like that - normally the C generating and building steps are transparent, and one just cares about the final executable program or module when using Cython.)
From my reading of your question, Cython is not what you want at this moment.
How can I get the python document in Emacs.I list two ways.
1、Using the man command?But I don't know where to download man file.
2、Some people suggest me to use dash in Emacs.What's dash.I can't find dash-mode in Emacs.
Both Elpy and Anaconda-mode have ways of looking up Python documentation:
In Elpy: https://elpy.readthedocs.io/en/latest/ide.html#command-elpy-doc
In Anaconda-mode: https://github.com/proofit404/anaconda-mode#eldoc
I have used both these packages in the past, and both are great!
I generated the Python docs in info format and use the info reader in Emacs. The Python documentation is spread out and the info reader is great at bringing those disparate pieces together.
The first step is to get a copy of the Python documentation in info format. The Python project does a great job making it easy to generate it (the info files themselves probably aren't distributed because the rst-to-info conversion isn't perfect). I detailed how to generate the Python docs in info yourself in this response. The process and the resulting info files are also hosted here.
To read an info file in Emacs, use C-u C-h i to be prompted for the file path. If you have the info file installed on your system (detailed here), you can use C-u 2 C-h i (or any other number, 3, 4, 5, etc.) to open a separate info buffer. This allows you to have multiple copies open side by side.
You can search the entire manual forward using C-s and backward with C-r. Use m to goto a menu item; press tab to see completions. Similarly, use g to jump to a node. You can press tab on a page to move the cursor the the next link. Use, l for the last page, u to move up a node, t to go to the "top" of the manual. Running info-apropos will generate a menu of all places in the manual that contain a search term. Execute M-: (Info-goto-node "(info)") to visit the Emacs info manual (which is somewhat different from the standalone info reader). The info reader has a lot of helpful commands!
I need to use python to pre-process docx (Word) documents, so that pandoc can properly convert them into markdown. One of the key requirements is that the styles of the docx document should be "cleaned up", in particular that the numbering of headings (Heading 1, Heading 2, etc.) should be removed.
Restrictions: I know how to do that using VBA (and likely could do it from python using PyWin32 or such). But it is a requirement that it must be implemented without Microsoft Windows and without LibreOffice/UNO.
How can I use the python-docx package to do that? I have looked at the documentation and there does not seem to be any proper to do it (actually the heading numbering style does not seem to be implemented). Did I miss something?
Unless I should use another method, such as applying a different Word template to the docx document, with the main styles correctly predefined according to my requirements? Could that be done through an available python package?
Code in VBA
This is the code in VBA that got the job done:
Sub RemoveHeaderNos()
' Remove the header nos
Debug.Print "Removing header numbers and formatting..."
For Each s In ActiveDocument.Styles
s.LinkToListTemplate ListTemplate:=Nothing
Next
End Sub
On terminology, I'm understanding you to mean "the numbering of heading paragraphs" as opposed to something like page numbers in the page headers, have I got that right? The two terms "heading" and "header" are unfortunately close and mean quite different things, in Word parlance anyway :)
I'm assuming your paragraph headings are numbered, like 'Heading 1' style causes the next sequential integer to be prefixed to the heading paragraph text, like '9. Ninth section heading', (then likewise for Heading 2 -> 9.1, 9.2, etc.
You're correct that this hasn't been implemented in python-docx yet. You would need to get as close to the XML element in question (perhaps the <w:style> element for Heading 1 for example) as possible using the python-docx API, and then use lxml calls to manipulate the XML under that.
You'd need to start with a strategy for what XML changes you need to make. opc-diag is handy for that. You can change the .docx manually (preferably a radically stripped-down, super-short document) using Word to make it look the way you want, then compare the XML before and after to discover what changes you need to make to the XML.
Then you can validate your strategy by extracting a .docx (using opc-diag), manually updating the XML with the minimum required changes, repackage it (also using opc-diag), and load it in Word to make sure it behaves as expected.
I suspect there's a way to "disconnect" the "Heading 1" style from a numbering definition in the styles.xml part that would accomplish what you're after and be a fairly straightforward handful of element changes.
Anyway, that's where I would start.
This issue was solved in version 1.17 of pandoc, released on 20 March 2016 ("Don’t turn numbered headers into lists"). If other people meet the same issue, the best thing at this stage would be to upgrade to a that version or a later one.
Nevertheless, the exploration of the various solutions with the python-docx was interesting, because it indicated a point of possible improvement.
I use cvs to maintain all my python snippets, notes, c, c++ code. As the hosting provider provides a public web- server also, I was thinking that I should convert the cvs automatically to a programming snippets website.
cvsweb is not what I mean.
doxygen is for a complete project and to browse the self-referencing codes online.I think doxygen is more like web based ctags.
I tried with rest2web, it is requires that I write /restweb headers and files to be .txt files and it will interfere with the programming language syntax.
An approach I have thought is:
1) run source-hightlight and create .html pages for all the scripts.
2) now write a script to index those script .htmls and create webpage.
3) Create the website of those pages.
before proceeding, I thought I shall discuss here, if the members have any suggestion.
What do do, when you want to maintain your snippets and notes in cvs and also auto generate it into a good website. I like rest2web for converting notes to html.
Run Trac on the server linked to the (svn) repository. The Trac wiki can conveniently refer to files and changesets. You get TODO tickets, too.
enscript or pygmentize (part of pygments) can be used to convert code to HTML. You can use a custom header or footer to link to the actual code for download.
I finally settled for rest2web. I had to do the following.
Use a separate python script to recursively copy the files in the CVS to a separate directory.
Added extra files index.txt and template.txt to all the directories which I wanted to be in the webpage.
The best thing about rest2web is that it supports python scripting within the template.txt, so I just ran a loop of the contents and indexed them in the page.
There is still lot more to go to automate the entire process. For eg. Inline viewing of programs and colorization, which I think can be done with some more trials.
I have the completed website here, It is called uthcode.