By default, RhodeCode supports RST-style comments. The docs indicate that both markdown and RST are supported in the README file. Is there a configuration option or plugin that allows you to switch to markdown-style formatting in the code review comments?
In 2.2.X Series default renderer is RST only, in next release 2.3.0 you can set default renderer to be either RST or Markdown.
Related
I am using sphinxcontrib.confluencebuilder to publish my Python documentation to Confluence cloud.
It creates labeled pages with the header/footer macros I need but it does so in the old Editor V1 format.
I haven't been able to find a config setting to tell it to use the Confluence V2 editor format. Is there a way to do so?
Also, the various extensions (myst-parser, m2r2 etc) for processing MD files work fine when outputting HTML but don't seem to take effect when publishing to Confluence. I'm using shell scripting and awk to convert MD to RST files but is there a better way?
Eventually this is going to run within a GitHub workflow.
The extension as of v2.x now supports the "v2" (Fabric) editor format. This can be configured using the confluence_editor option:
confluence_editor = 'v2'
There are limitations when using the editor, which are outlined in the extension's documentation and demonstration pages.
Disclosure: I am a maintainer for the Atlassian Confluence Builder for Sphinx extension.
I have a free private github repo. I would like to have in a docs folder the docstrings turned into rst files.
This is what sphinx does, but generate html instead of rst.
For all rst files generated this way (let's imagine one rst file per python module), I intend to hyperlink it from the readme to have access to the code documentation this way (without having to rely on github pages, which I have no access to, given I have a free account).
Please, is this possible?
Ideally, I would need a way to tell sphinx autodoc extension to generate documentation in rst instead of html, but I haven't found a way for this.
Is there another lib for this?
Thanks for any help,
Bests,
As proposed in comment from #mzjn, I used sphinxcontrib-restbuilder for this purpose.
Hyperlinks work, this is perfect for my need.
I applied it on the sphinx documentation of a public project of mine, and uploaded it on this github repo for those willing to have a look.
Click on index.rst and follow the read. There do be some glitches.
The API is documented in api.rst. This is really this part that is of interest for me.
I think it is nice enough.
Is there any plugin on embedded feature in JetBrains IDEs to make comment more visualize or stylise.
I used comment-snippets in sublime-text, which provide some cool eye catchy comments like
/*=============================================
= Section comment block =
=============================================*/
/*===== End of Section comment block ======*/
Please suggest, Is there any plugin or native feature to accomplish this?
Have you checked Live Templates?
Settings/Preferences > Editor > Live Templates
In my opinion it provides same functionality.
Ruby has a few good document generators like Yard, rDoc, even Glyph. The thing is that Sphinx does websites, PDF's, epub, LaTex...etc. It does all these things in restructuredtext.
Is there an alternative to this in the Ruby world? Maybe a combination of programs? If I could use Markdown as well that would be even better.
Since version 1.0, Sphinx has had a concept of "domains" which are ways of marking up code entities (like method calls, objects, functions, whatever) from lannguages other than Python and/or C.
There is a ruby domain, so you could just use Sphinx itself. The only thing you would be missing (I think) is Sphinx's ability to create documentation from source automatically using the autodoc extension, which works specifically on Python code.
If you want to use Markdown, you might check out JDoc, which is a very simple, Ruby-based documentation framework that lets you use widely-supported markup and put it under source control. It lets you edit the documentation in your text editor of choice, and it supports:
Markdown or Textile
syntax highlighting
easy internal links
a hierarchical documentation structure (useful for large projects)
customizable styling and structure (but it looks nice out of the box, too)
It generates static HTML, so the resulting documentation is easy to host and doesn't have much of an impact on your server load.
To see it in action, check out wpmvc.org.
Another couple of options would be to use Middleman which is a static site generator that accepts either Kramdown or Markdown as input.
There are also frameworks that are designed specifically for technical documentation that use Middleman (both of which are on GitHub) including lord/slate and pnerger/dpslate (the later is a fork of the former and provides some enhancements that were not appropriate for pulling). The Slate format provides a format for documentation that includes many of the features of Sphinx with some additional enhancements. It features a three-pane view of a document which includes an automatically generated Table of Contents, a Main center body, and then sample code panel to the right. Like Sphinx the sample code has syntax highlighting.
I am currently starting to write a documentation for one of our projects. For reasons of simplicity we chose to use the Almost Plain Text (APT) Format, see more info here:
http://maven.apache.org/doxia/references/apt-format.html
APT is great documentation format, since it uses a minimal syntax and hence it is very easy to create and make changes to the documentation without knowing a lot about APT.
However, I couldn't find a way to format code in a nice way. Is there a code tag or similar, which can be used to include some source code? I'm aware I could use FML, but this would be less desirable.
Thanks
For those who are still wondering how to make a code snipped in APT:
This is regular text
+---------------------
This is a code snippet
+---------------------
More regular text
Apache Maven Fluido Skin highlights syntax out of the box. Here you can find an example. Information about syntax highlighting in Fluido: "Source code sections are enhanced by Google Code Prettify, users can optionally enable line numbers rendering (disabled by default)" from Fluido website.
The
+---------------------
code
+---------------------
syntax is correct. And Fluido does highlight using Prettify out of the box as others have mentioned.
However, a Doxia change in Site Plugin 3.3 broke Fluido. MSKINS-86 fixes this, but hasn't been released yet.
Workarounds
Use the site.xml workaround
<body>
<head>
<script type="text/javascript">
$(document).ready(function () {
$("div.source pre").addClass("prettyprint");
prettyPrint();
});
</script>
</head>
</body>
Use Site Plugin 3.2
Build the unreleased Fluido 1.4 that contains MSKINS-86 fix and use it instead of 1.3.1
I ended up using the snippet macro from the Doxia Macros Guide: http://maven.apache.org/doxia/macros/index.html#Snippet_Macro
It puts the code from the snippet file in a verbatim box. However it does not provide a syntax highlightning.
Version 1.0 of doxia include macro is not at maven central however the following versions are:
http://mvnrepository.com/artifact/org.tinyjee.dim/doxia-include-macro