I have a swagger.yaml/.json file with documentation about my API. Now I want to generate static file from it. But I would like to customized it more than change color of Button. E.g. I want to change place where the button is or how big it is. After that I would like to get index.html as one file.
I've found something like redoc-cli or swagger-codegen but non of it helps me with my problem. I can only chose 'theme'. Is there any kind of tools which helps me with this?
HTML tags work in swagger .yaml/.json file, so actually you can create almost any design you want inside swagger file (not only openapi syntax works for designing documentation).
The final visible output depends on the environment and how do you plan to use the swagger file.
Related
A while back, i made my very first Github repo. Since i added the documentation using HTML and CSS, github doesn't recongize it in the "Languages" bar. It only shows 100% Python.
How can i change it so it also includes HTML and CSS???
The "Languages bar" as you called it is powered by Linugist. According to their Documentation, Linguist ignores (or tries to ignore) generated files, binary data, documenatation and similar files.
Github's Linguist probably "ignores" your documentation folder which contains html and css or just understands that the most important code is Python.
Anyway, you can edit .gitattributes to show exactly what you want.
More info here https://dev.to/katkelly/changing-your-repo-s-language-in-github-5gjo
How do I convert an HTML file with content folder to a self-contained HTML file which can be viewed from anywhere with its images etc.
How can it be done so that it's also editable and stays self-contained, post-edit?
I basically need to make HTML file based documentation which can be viewed from anywhere. Unfortunately it HAS to be HTML, otherwise I would have made PDFs
You can use pandoc, it has an option to create self-contained html files https://pandoc.org/MANUAL.html#option--self-contained.
If you start with html, this is the command.
pandoc in.html --self-contained -o out.html
This tool can do a lot more things, for example, you can also generate html from markdown files or generate pdfs instead.
The most direct way is to convert all asset urls to data: urls. (There are online coverters available that will take a provided asset and produce a data: url from it.)
A possibly simpler way is to convert image and font urls to data: urls while instead inlining scripts and css.
Edit: Possibly of interest: inliner, a Node utility for doing this kind of thing. "Turns your web page to a single HTML file with everything inlined". Also performs a number of minifying optimizations.
I don't know exactly what you're envisioning, but HTML was never meant to be fully self-contained. There may be some loopholes that allow it in the end, but to my knowledge there are no premade tools that do this 'conversion'.
It would require the following things:
Converting all linked style sheets and scripts to inline style sheets and scripts. This means that whenever there's a <script src="http://url.to/foo.js"></script> you'll have to download foo.js and include it as such: <script type="text/javascript"> [this is the content of foo.js] </script>. Something similar applies to CSS and other linked source files.
Downloading all linked media (images mostly, I presume) and converting them to blobs (a service that provides you with a base64 blob you can use within a HTML file is https://www.base64-image.de/). This means replacing <img src="http://url.to/image.jpg" /> with <img src="data:image/png;base64,[converted image data goes here] />.
So there's gonna be some manual labour involved there, but it probably can be done (almost) fully.
Possibly there's a way to accomplish what you're wanting to do another way though, what exactly is your reason for wanting this?
Here's another option: write your documentation in markup, then use a tool such as "Marked 2" (http://marked2app.com) to convert to self-contained html. Works slick. Plus you can go back and edit the markup any time you need to update your documentation, then simply re-export your html file.
I am trying to include some images in a Genshi template for my Trac plugin, but it always shows only the alternative text because it cannot find the images.
I have the following (X)HTML code:
<div>
<img src="file://c:/path/to/image.png" alt="asdf" />
</div>
When I use this code with a simple html file and open it in the browser, the image is displayed correctly, which means that both the path and syntax are correct.
But when I insert the code snippet into a Genshi template and use it within Trac, the image cannot be found. However, when I look at the HTML source code in the web browser and copy the URLs into a new browser tab, it is again displayed correctly. This means that only the server cannot find the image.
The images are in a directory inside the python-egg file, and the path points directly to the directory created by Trac, which also contains my CSS and HTML files, both of which are loaded correctly. The images are correctly referenced in the setup script which creates the egg.
How do I have to reference images in (X)HTML documents when using them with a server?
Is there a special way to include images in Genshi documents? (I haven't found one.)
Thanks to the comment of RjOllos and this site I was able to fix it by trying all of the URL types. Although it says for a plugin to be /chrome/<pluginname>, it was actually just /chrome that worked. See the edit below! So the full URL is then <ip>:<port>/chrome/path/to/image.png.
EDIT: I discovered I actually used the /chrome/pluginname version, just that I did not use the name of my plugin as "pluginname". See my comment below. It seems like /chrome/pluginname should actually be /chrome/htdocsnameor something like that, in case you use a different name rather than the plugin name when implementing the ITemplateProvider. In my case I called it images, which was the same name as the folder. END OF EDIT
Another mistake I made was forgetting the initial slash (chrome/path/to/image.png), which caused Trac to assemble the URL to <ip>:<port>/<current page>/chrome/path/to/image.png.
Some of the gnome applications on linux use a help browser called yelp. For example, the gnome-calculator, gcalctool, has its help files located in /usr/share/gnome/help/gcalctool
The folders there are then sorted by language. These help files essentially consist of an xml file and some accompanying png figures.
What I'm trying to do is convert this xml and its accompanying png figures into static HTML because I want to be able to properly view and navigate the document from a different browser (firefox). If you want to see what I'm talking about and you are on Linux, just run gcalctool and open the help menu.
Unfortunately, opening the xml directly with firefox is not successful because there are no stylesheets and thus firefox doesn't know how to format it. I have read that gnome applications make use of a library called libxslt (http://xmlsoft.org/libxslt/) for applying stylesheets. I am not familiar with xslt at all. Are the stylesheets saved elsewhere, or embedded in the source when it is compiled?
I guess what I'm wondering is if it's possible to somehow use libxslt by itself or another tool to convert the xml and figures into static HTML, preferably in the same manner yelp does this when it executes, or in a manner that results in an exact/very similar output to what yelp displays.
Thanks
gcalctool uses docbook. Yelp brings everything to display this xml format. You will find some projects to convert this docbook document to html on http://wiki.docbook.org/DocBookToXhtml.
best regards
Majo
Depending on how old your gcalctool is, its help files might be in DocBook or Mallard. If it's Mallard, you'll see a bunch of .page files. Otherwise, it's DocBook. Either way, you can use yelp-build to create HTML files. It's part of the yelp-tools package, and uses the same transformations as Yelp. For DocBook, pass the top-level XML file:
yelp-build html -o /path/for/output/ /path/to/gcalctool.xml
For Mallard, pass the directory containing the .page files:
yelp-build html -o /path/for/output/ /path/to/gcalctool/
yelp-build will build the HTML, copy the images and other media files, and take care of the CSS and JavaScript.
I work on a very large enterprise web application - and I created a prototype HTML page that is very simple - it is just a list of CSS and JS includes with very little markup. However, it contains a total of 57 CSS includes and 271 javascript includes (crazy right??)
In production these CSS/JS files will be minified and combined in various ways, but for dev purposes I am not going to bother.
The HTML is being served by a simple apache HTTP server and I am hitting it with a URL like this: http://localhost/demo.html and I share this link to others but you must be behind the firewall to access it.
I would like to package up this one HTML file with all referenced JS and CSS files into a ZIP file and share this with others so that all one would need to do is unzip and directly open the HTML file.
I have 2 problems:
The CSS files reference images using URLs like this url(/path/to/image.png) which are not relative, so if you unzip and view the HTML these links will be broken
There are literally thousands of other JS/CSS files/images that are also in these same folders that the demo doesn't use, so just zipping up the entire folder will result in a very bloated zip file
Anyway -
I create these types of demos on a regular basis, is there some easy way to create a ZIP that will:
Have updated CSS files that use relative URLs instead
Only include the JS/CSS that this html references, plus only those images which the specific CSS files reference as well
If I could do this without a bunch of manual work, if it could be automatic somehow, that would be so awesome!
As an example, one CSS file might have the following path and file name.
/ui/demoapp/css/theme.css
In this CSS file you'll find many image references like this one:
url(/ui/common/img/background.png)
I believe for this to work the relative image path should look like this:
url(../../common/img/background.png)
I am going to answer my own question because I have solved the problem for my own purposes. There are 2 options that I have found useful:
Modern browsers have a "Save Page As..." option under the File menu, or in Chrome on the one menu. This, however does not always work properly when the page is generated by javascript
I created my own custom application that can parse out all of the CSS/Javascript resources and transform the CSS references to relative URLs; however, this is not really a good answer for others.
If anyone else is aware of a commonly available utility or something like that which is better than using the browser built in "Save page as..." option - feel free to post another answer.