There are lot of Swagger related codegens to convert a YAML to HTML file , but is there an eclipse plugin available which can open or convert a YAML to HTML ?
I have searched in multiple places but there's no place where we can find such a plugin .Plugins like Yedit help seeing a YAML in colour syntax form but not as a HTML ?
You might want to take a look at RepreZen API Studio, available as a standalone desktop application or as an Eclipse plugin.
It includes swagger-codegen and other open source generators, which can create various forms of HTML documentation from your YAML-formatted Swagger-OpenAPI spec. Code generation is fully integrated into the IDE, but can also be run from the command line or CI/CD automated builds.
To clarify, there's no HTML "equivalent" of a Swagger-OpenAPI spec, or any other form of YAML. So it's not a simple matter of converting one file format to another. But there are various components that render a machine-readable OpenAPI spec, in YAML or JSON form, in a user-friendly HTML documentation format, often with integrated sandbox testing.
One of these is Swagger-UI, and it's included in the HTML formats that are supported by RepreZen API Studio. I hope that helps.
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 need to write and build easy maintainable, goodlooking, esay to change documentation in pdf and html 5 format. The source format must be easy to edit. This maven plugin has to support my company organziation theam(fonts, colors, pictures etc.), TOC generation, separation of chapters in different files, integration of images files, easy way to put code snipets in the documentation. I have Maven build and I was wondering what is the current best descision to do that?
I was investigate two options:
Doxia - using md(markdown) as input format. There is WSWG md free
editor, support a lot of the aforemention stuffs, etc. Need external repo for its artifacts.
Asciidoctor - use asdcii doc as input format. Support templating using fragments etc.
What are the advantages and disadvantaes of using this plugins?
Are there any other good solutions?
From my attempts to build the documentation first with Doxia and then with AsciiDoc I realised that Asciidoc is the better. It allows
Easy styling using yaml files. Default styling is also very good.
Asciidoc as a mark-up language is very good documented: Uder Guide AsciiDoc
Has good online editors and the language is more powerful than markdown for example, and easier to write in comparison to the xml format.
Good examples when using with Maven and ascii doc and easy to understand configurations.
I have lot of documentation written in AsciiDoc and correctly separated into folders. I use asciidoctor with a custom CSS to render my docs to HTML. The problem with this is that it generates a single HTML page that is very long. I was surfing the web and found that the atom docs are also written in AsciiDoc, but these docs have not all the information together, in fact they are separated into different sections.
Here the atom docs: https://atom.io/docs/v0.201.0/getting-started-why-atom
I want to know if there is a tool that can generate this, a flag or a specific syntax.
I think it is not really user friendly to have all the info in one long single page.
I have a site where the static content is generated using the asciidoctor-jekyll plugin and jekyll.
I had also plugged the java version of asciidoctor to generate views with the play framework at some point but decided that I prefer that the content I generate with asciidoctor to be static and delivered by a CDN.
EDIT:
Also, GitBookIO supports asciidoctor.
We have a very old application dating back to ASP era which we are gradually refactoring to ASP.NET + VB.NET codebase.
It contains a lots of files with the below types:
aspx, asmx, ascx, vb, js (JavaScript), html, vbs (VBScript).
The backend database is SQL Server 2005 with lots of sprocs.
We would like to create a code documentation automatically generated from the comments in the code files. I liked Doxygen very much but seems like it does not support the above technologies. Can you please suggest some document generator tools, preferably a single tool or a group of tools?
Thanks a lot.
Ajit.
You can take a look at Microsoft's Sandcastle tool. I've used it many times, and it generates documentation based on the comments provided in your .NET code. If I remember correctly, it can also generate documentation for JavaScript libraries.
There are some out there:
SandCastle
NDOC
i've used SandCastle and it works too good if you have xml comments in your code.
You first enable xml documentation in your project by setting it in Project Properties -> Compile -> Generate XML Documentation.
Once done you may have to set treat warnings as errors, so that the studio can point out to you where and all the XML comments are missing.
To add an XML Comment, you place your cursor before a class definition or a function definition and type
///
This will automatically generate xml tags for documentation and then once you are done, you can import the project and start to build the documentation.
The good part is, if you have documented your classes well, when you use those functions in your application upon mouse over you can find the description which you wrote, much like how intellisense documentation works.
Let me know if you run into any other issues.
My last suggestion, make a hello world project and xml document it and get used to sandcastle with it.
Anyone know of a wiki or wiki plugin that generates a PDF file or CHM file that spans the entire wiki?
I would like to have control of the table of contents.
I would like the internal and external links to work.
Ideally allow for tweaking the output template, but that is not a deal-breaker.
I want to generate content using WIKI syntax and mindset (lots of cross-links etc), but ship the content in PDF, CHM or an embedded application form. Something friendlier than installing the wiki software on the enduser machine...
XWiki does this out of the box.
The MediaWiki PDF Export extension allows you to select a group of PDF pages. I've not installed it yet, so unsure if it's easy to use that feature to select all the pages.
Confluence lets you choose pages when you export to PDF a space
But you can't customise a lot the PDF
You can customise it slightly through a theme (based on velocity)
Sphinx (https://www.sphinx-doc.org) is a fairly nice tool for generating HTML (or CHM) and PDF documentation, with wiki-like syntax. It is not a wiki; you can't edit through the web and generating HTML requires a build process. Still, it is pretty nice, with cross-references, fairly simple markup, and (in the HTML output) a search engine implemented in JavaScript with no server-side dependencies beyond static file hosting. Sphinx was developed for the new version of the Python documentation and is pretty themable; for example, the GeoServer project (which I work on, excuse the shameless plug) is using Sphinx with a custom theme for the new version of their user and developer manuals.
JIRA (http://www.atlassian.com/software/jira/default.jsp) is your geeky wet dream in terms of control; it exports to PDF (amongst other) and you can have complete control of pages, TOC and other aspects, although expect some complexity to set it up.
Microsoft has an HtmlHelp Authoring tool that can create chm files from html files.
If you need the help files both on the web and within deployed applications, generating the help from the same files used on the web could be a great solution. If the help site was created using asp.net (ie database driven) it might be worth using basic styles and creating a tool to generate html files by reading in the served out pages?
Have a look at: http://msdn.microsoft.com/en-us/library/ms524239(VS.85).aspx
I guess one could also additionally then create a PDF from the Html pages?