I'm going to manage some documentation using Django (I come from Sphinx) in order to have more control on the output. The docs are in rst (restructured text) in a git archive, and it's trivial to display them in HTML using a filter. My problem is that they are quite long, and I'd like to have more control on how the pagination goes, so I can show a single section per HTML page, have comments for a single section and so on...
My goal would be to be able to parse each doc, create my TOC with links to each section in a separate HMTL page, where a view would go through whole doc to render in html just a section.
I understand that it's mostly a issue of docutils, the most interesting example I've been able to find is: http://www.ibm.com/developerworks/library/x-matters24/#code2 but it seems outdated and the examples in section "Tree-oriented processing", which is where the magic goes, don't seem work with my version of docutils. Article is good: I could use more of the same subject!
Is there something similar to what I'm planning to do already available that I can study, or maybe could someone point me to a gentle introduction to docutils for parsing rst documents?
Here is a blog describing howto make a custom rst writer and call it from Django. I think it should give you a good start http://www.arnebrodowski.de/blog/write-your-own-restructuredtext-writer.html
Pygments has a ReST lexer that you could examine (or possibly even use directly).
Related
I have a set of .groovy files (Java). All of these files have the same comment format.
I developped a tool with wich I'm able to read those files and applying a REGEX to get all the comments in a list. (Finally i just have to copy paste these comments to .html file)
I would like to know if it's a correct practice in order to generate a HTML page with the comment (a kind of documentation). If not, what would you recommend ?
I read about Doxygen and Javadoc but i'm not sure about using them (if they can be really useful in my case since the comments are already written)
If you can suggest a library in order to generate easily a HTML Webpage or any other advice.
Any help is appreciated.
There exists Groovydoc which is roughly the equivalent of Javadoc, just for Groovy.
As your setup is not that (you already have comments, probably not in Groovydoc format, and you have half the tooling), there are still multiple ways open to you. As you already extract the documentation from groovy, if I were you, I would do a minimal post-formatting, if necessary, and output the documentation as markdown (e.g., github markdown) or asciidoc (e.g., asciidoctor). Then you can use any preferred tool to convert the post-formatted documentation into HTML.
To answer the question "How to parse the java comments" – you shouldn't. If possible, especially in a new project, stick with the standard tooling. In the case of Groovy that's Groovydoc. The normal (non Java/Groovy-Doc style) comments themselves you should never need to extract from the source code. They should be so much context-specific, that without the corresponding code they are anyways useless.
I have a Django Project where I used Sphinx to create my documentation. I went through sphinx-apidoc and ran 'make latexpdf'. The resulting documentation has a quite a few lines that flow out of the margin. On top of margin issues, lines in the index start overflowing onto each other.
Overflowing Lines
Margin Issues :(
Is there an easy way to fix these issues (or an easier way to create PDF documentation)?
ELI5 if possible (I'm not well-versed in LaTeX)
The overflowing lines situation in the index should improve from adding this to conf.py:
latex_elements = {
'printindex': '\\footnotesize\\raggedright\\printindex',
}
Or, you can switch to Japanese language which does something like that (even better) out-of-the box from its special document class ;-)
TeX does not always know how by itself how to insert linebreaks: after all it is good at hyphenation of natural language. But as pointed out in comments Sphinx coerces LaTeX into handling better long code lines since 1.4.2.
Since recent 1.5.3, user can customize page margins, check http://www.sphinx-doc.org/en/stable/latex.html#the-sphinx-latex-style-package-options for documentation of hmargin and vmargin which can be configured via 'sphinxsetup'.
I am writing a webserver in C++. I am looking at the POST documentation on w3:
http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4
I see that a POST is supposed to support the full multi-parts scheme: parts and sub-parts (and obviously, sub-sub-parts...) just like for email attachments.
Is there any browser and/or tool that do that on a normal basis? In other words, is it really important for a server to support parts and sub-parts?
The obvious problem with that is the fact that it could mean that two files are uploaded under the same name. That's quite a problem if you ask me. Also, from what I can see in PHP it is not supported at all in that realm. Am I correct?
Ah! I guess I should have searched a little more and to tell you the truth I had not thought of looking at HTML5 for the answer.
The following paragraph actually includes the answer:
http://www.w3.org/html/wg/drafts/html/master/forms.html#multipart-form-data
Note: In particular, this means that multiple files submitted as
part of a single element will
result in each file having its own field; the "sets of
files" feature ("multipart/mixed") of RFC 2388 is not used.
So it is clear that sub-parts (multipart/mixed) are not to be supported.
Is it possible to embed code to Trac wiki page straight from source code? I mean code blocks, not links pointing to the source. Like
MyCode.java contents
Look at IncludeMacro which is also able to embed from source repository (keyword source:).
Furthermore you can copy source code to wiki and format it with syntax-highlighting, for example:
{{{
#!python
hello = lambda: "world"
}}}
Read more about it here.
You're using 'code blocks' in a way that makes me think of partial citation.
As falkb pointed out, IncludeMacro is the current best way of embedding Trac (and even external) content into a Trac resource, that is rendered with support for Trac's WikiFormatting. But sadly, there is NO such partial citation capability yet.
You may want to at least request it as enhancement for the aforementioned plugin, and could even push it closer to reality by providing valid use case example - or better: some real code to make it happen. Be prepared to test code, if a patch is proposed or - ideally - if the trunk (development) branch receives changes to make partial citation happen.
I have a fairly extensive wiki on ZWiki on Zope (in turn on Plone). Most pages are in reStructured text format, but there are several in straight HTML as well.
What is the best approach to migrate those pages over to a MediaWiki wiki with pages converted to MediaWiki and HTML formats? Of course I'd like to automagically convert all links (internal and external).
extract your wiki content to files, using the zwikiexport.py script. The command will be something like:
ZOPE/bin/zopectl run ZOPE/Products/ZWiki/bin/zwikiexport.py /zodb/path/to/wiki/folder
convert the restructured text markup to mediawiki markup. pandoc should work well - for each wiki page, run something like:
pandoc -r rst -w mediawiki PAGE.rst >PAGE.mw
convert the wiki links, which pandoc doesn't know about. Depending on your content, this may be the hardest part to do accurately. Write a perl script, or modify the zwikiexport script, using Zwiki's knowledge of where the links are (see methods in ZWikiPage.py).
import the mediawiki-format pages into mediawiki, however that's done
refinements:
the exported file tree will reflect your zwiki page hierarchy - if you use this heavily, you'll want to think about how to represent it in mediawiki
as Mark says, you'll lose the page history, unless you work extra hard to find a way to replicate that. The same goes for all page metadata you may have have been using (you can inspect most of this metadata in the page's Properties tab in the zope management interface). In particular the page creation time, last edit time, and the usernames of the page's creator and last editor are quite important, to understand your content. So I would try to script some way of preserving those or if all else fails, doing it by hand.
if you have uploaded files to the wiki, I think the export script might save those too, otherwise use the ZMI to export/save them. When you import them to mediawiki, you may need to choose a page to attach them to. You could use grep or Zwiki's search to find the pages that reference a particular file.
be prepared to iterate, testing the results pretty thoroughly and refining the process, before you declare victory. After that, the content will diverge and you won't want to re-do this.
manual fixups: at some point, it may be cheaper to stop fiddling with scripts and do the remaining cleanup by hand, by yourself or with an army of helpers.
Good luck! - Simon
http://zwiki.org
I've no experience of ZWiki and don't know how large your wiki is. But general advice - you can use find / replace in Notepad or Notepad++ - or you can write a macro in Excel.
This is per page copying which is only really suitable if your wiki is not larger than, say, 1000 pages.
I suspect you'll still have manually to check each page though, and update your scripts accordingly.
Good luck with it - I suspect you'll be pleased with the final result because MediaWiki is pretty awesome.
Update: one disadvantage of moving to a new wiki is that you will lose the page history (i.e. who wrote what, when).