We have an internal python API that we have documented using Sphinx. part of the system uses YAML for configuration files that contain reference to py file that use the API. I've been asked to see if there is a way, using sphinx, to link the YAML config files to the the appropriate API docs. I've been doing research on google, here and sphinx site and it looks like I may be able to use intersphinx but I'm unclear how to make the connection between the two.
so for example: here is the yaml config file:
HALT_LEVEL: Any
SUITE: "Checkin Tests"
DESCRIPTION: "checkin test suite"
TESTLIST:
- TESTCASE: install stuff
DESC: "Installs RPM"
TESTGROUP: sprint_0
TESTFILE: install_stuff.py # I would like to turn this into a link to our sphinx docs
# for this. This file is already part of sphinx docs"
So then when someone is looking at the html/sphinx version of the the above file they could click on install_stuff.py and it take them to the docs that exist
Is this possible?
thanks in advance,
Greg.
Just for those that may be interested. I was able to do this but not using Sphinx. I used pyyaml to read the file and pygments to generate the html then hacked the generated html.
Since pygments doesn't appear to allow live href links what to add them what I is
# create a yaml string using pyyaml and then modify the string.
href = '[ahref="%s"]%s[/a]' % (hrefData, hrefString)
yamldata['KEYWORD'][idx]['HOST'] = href
This changes the referenced yaml to a string that looks something like '[ahref="http://example.com"]Example.com[/a]'. The brackets make it easier to change after the html is generated. Further down in the code I use pygments to generate the html
htmlpage = highlight(yamldata,lexer, HtmlFormatter(full=True, title=yamldata['TITLE']))
Now I convert the href that I created above to a real href with:
webpage = htmlpage.replace(''', '').replace('ahref', 'a href').replace('[','<').replace(']','>').replace('"','"')
Related
I am new to parsing the xml in the ruby and I am stuck with an issue. I'll try my best to explain.
I get the below response from an api
"PK\x03\x04\x14\x00\b\b\b\x00,\x18ET\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x1D\x00\x00\x00"
I believe it is .tds format.
I am trying to parse it into a valid xml so this is what I tried.
xml = Nokogiri::XML(response)
which gives me #<Nokogiri::XML::Document:0xf744 name="document">
Then I tried to do Hash.from_xml(xml.to_xml)
But this throws error The document \"<?xml version='1.0'?>\\n\" does not have a valid root
Any idea what am I missing here?
This string starts with "PK", which are initials of Phil Katz, author of the ZIP format. Which means it's a ZIP file. There are certain formats that are ZIP files, but actually follow some further structure conventions, like Java JAR files, but also all OpenDocument formats like .ods, .odt and all MS Office Open XML formats.
Since you are probably expecting an .ods file... While you could unzip it and then use Nokogiri to parse the XML, there's a better way to proceed.
There's an interesting Gem called Roo, that supports all most common spreadsheet formats and produces a nice Ruby API to deal with them: https://github.com/roo-rb/roo
I would recommend you to save the string to a temporary file and then open it with Roo.
I made an XML configuration file that contains information to be accessed from both my Ruby script files and my HTML files. For Ruby purposes, this file contains things like links and admin authentication credentials that the script will need to pull from my database (I know this isn't safe--that's not an issue for me right now). For the HTML, it contains titles and other graphical information for the widgets where I'll be displaying this received information.
I was able to access the XML file in Ruby with the following:
require 'xmlconfigfile'
parent_directory = File.expand_path(".")
config = XmlConfigFile.new(parent_directory + '/configuration_file.xml')
info_i_need = config["/config/path_to_info/the_info"]
No problems there. Now, in the HTML, each widget is assigned a name, and I'd like to replace those names with strings that are located in this XML file. So I tried using embedded Ruby:
<div data-title=<% XmlConfigFile.new(File.expand_path(".") + '/configuration_file.xml')["/config/path_to_info/the_info"] %> ></div>
I didn't really expect this to work. I'm not sure if you can/should access Ruby packages in this way, but I can't find any other way to get the information I need into the HTML.
I really appreciate any corrections to this code or suggestions to alternate approaches. Thanks!
For some REST APIs written in PHP, I was asked to create Swagger documentation, and since I was not aware of any easy way of annotating those existing APIs and create such a documentation, I used this editor to generate some for now.
I saved the JSON and YAML files created using that editor, and now I need to create the "interactive" Swagger documentation from there.
Can someone please let me know how I can convert the Swagger JSON specification file to an actual Swagger documentation?
I am on the Windows platform and do not know anything about Ant/Maven.
Try to use redoc-cli.
I was using bootprint-openapi by which I was generating a bunch of files (bundle.js, bundle.js.map, index.html, main.css and main.css.map) and then you can convert it into a single .html file using html-inline to generate a simple index.html file.
Then I found redoc-cli very easy to to use and output is really-2 awesome, a single and beautiful index.html file.
Installation:
npm install -g redoc-cli
Usage:
redoc-cli bundle -o index.html swagger.json
I was not satisfied with swagger-codegen when I was looking for a tool to do this, so I wrote my own. Have a look at bootprint-swagger
The main goal compared to swagger-codegen is to provide an easy setup (though you'll need nodejs).
And it should be easy to adapt styling and templates to your own needs, which is a core functionality of the bootprint-project
Everything was too difficult or badly documented so I solved this with a simple script swagger-yaml-to-html.py, which works like this
python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html
This is for YAML but modifying it to work with JSON is also trivial.
I spent a lot of time and tried a lot of different solutions - in the end I did it this way :
<html>
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist#3.17.0/swagger-ui.css">
<script src="//unpkg.com/swagger-ui-dist#3/swagger-ui-bundle.js"></script>
<script>
function render() {
var ui = SwaggerUIBundle({
url: `path/to/my/swagger.yaml`,
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
});
}
</script>
</head>
<body onload="render()">
<div id="swagger-ui"></div>
</body>
</html>
You just need to have path/to/my/swagger.yaml served from the same location.
(or use CORS headers)
Check out pretty-swag
It has
Similar looking as Swagger-Editor's right panel
Search / Filter
Schema Folding
Live Feedback
Output as a single html file
I was looking at Swagger Editor and thought it could export the preview pane but turned out it cannot. So I wrote my own version of it.
Full Disclosure: I am the author of the tool.
See the swagger-api/swagger-codegen project on GitHub ; the project README shows how to use it to generate static HTML. See Generating static html api documentation.
If you want to view the swagger.json you can install the Swagger UI and run it. You just deploy it on a web server (the dist folder after you clone the repo from GitHub) and view the Swagger UI in your browser. It's a JavaScript app.
You can also download swagger ui from: https://github.com/swagger-api/swagger-ui,
take the dist folder, modify index.html:
change the constructor
const ui = SwaggerUIBundle({
url: ...,
into
const ui = SwaggerUIBundle({
spec: YOUR_JSON,
now the dist folder contains all what you need and can be distributed as is
For Swagger API 3.0, generating Html2 client code from online Swagger Editor works great for me!
Give a look at this link : http://zircote.com/swagger-php/installation.html
Download phar file https://github.com/zircote/swagger-php/blob/master/swagger.phar
Install Composer https://getcomposer.org/download/
Make composer.json
Clone swagger-php/library
Clone swagger-ui/library
Make Resource and Model php classes for the API
Execute the PHP file to generate the json
Give path of json in api-doc.json
Give path of api-doc.json in index.php inside swagger-ui dist folder
If you need another help please feel free to ask.
There's a small Java program which generates docs (adoc or md) from a yaml file.
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.DE)
.build();
Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);
Unfortunately it only supports OpenAPI 2.0 but not OpenAPI 3.0.
If you commit your JSON file in Gitlab, it will render it for you.
Redocly's CLI interface has a tool to build HTML docs from OpenAPI spec files.
sudo npm i -g #redocly/cli
redocly build-docs my-swagger.yml -o docs.html
I have the following Ruby code processing a Markdown file:
html = Markdown.new(markdownContents).to_html
The result of this includes a comment block at the top of the file, which I would like it not to do, but I can't seem to find an option in the documentation to not render this comment block.
<!-- === begin markdown block =====================================================
generated by markdown 1.0.0 on Ruby 1.9.3 (2012-04-20) [i386-mingw32]
on 2012-08-15 15:34:51 -0400 with Markdown engine kramdown (0.13.7)
using options { !to be done! }
-->
Is there an option for this, or would I have to submit a pull request? ;)
The code to add this header seems to have been added in this commit and only applies to the kramdown engine. It seems the solutions are:
to submit a pull request with code to make this optional
configure Markdown to use a different engine. Details here in the Markdown Engine Loading Order section
Is there a schema validation language for YAML? I've googled but couldn't find anything useful.
Something like XSD format, using the language itself to describe the schema, would be the best choice in my case.
JSON Schema can be used with most YAML documents resulting in a more portable and better documented solution than Rx or Kwalify. JSON Schema is the only of the three for which I have been able to find editor support.
More information on using YAML and JSON Schema including tools and editor support is tracked on this page. At the time of writing, there is editor support in Visual Studio Code and a command-line based validation tool available via npm.
Full Disclosure: I authored the web site linked above to try to make the application of JSON Schema to YAML more discoverable. I also wrote an editor extension for VS Code that has since been superseded by the RedHat extension linked above.
Try Kwalify (Ruby and Java only), or Rx (many languages)
I wonder if it would make sense to reuse JSON schema for this. YAML can be easily converted to JSON without loosing any information (?), so in theory YAML could be validated by the same tool chain, allowing open source community to concentrate on one good schema tool chain. The schema itself could also be written in YAML and converted to JSON.
Good idea. Googled this up because I was looking for the same.
It's possible to convert YAML to XML in a defined manner (similarly to JSON <-> XML) and validate with a standard XML validator.
Depending on your platform, there are tools or snippets for that conversion: JavaScript (NPM), Ruby, Java (Jackson), Java (TestNG) (you'll need to see the source for what parameters it wants).
If done using an API, the error positions can even be mapped back to the original YAML file.
You can use this python ysd project to validate your yaml files. https://github.com/yonahd/ysd
Super simple to use
python yaml-validator/main.py -v yamls/example-values.yaml -r yamls/example-rules.yaml
Example rule file:
required: // field must exist and type must match
env: str
enabled: bool
replicas: int
optional: // if field exists type must match
disk: str
Example yaml file (helm values file):
network:
service:
port: 8060
enabled: true
image:
app: my-app:build
replicas: 1
env: dev
disk: local
If your project is in C++, you can also use the yaml-schema-cpp library. It allows to validate (and complete) the .yaml input files using schema files (YAML files with extension .schema) from your C++ code.