Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .ruby-version
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.6.2
2.7.1
64 changes: 38 additions & 26 deletions Gemfile.lock
Original file line number Diff line number Diff line change
@@ -1,24 +1,38 @@
GEM
remote: https://rubygems.org/
specs:
addressable (2.7.0)
addressable (2.8.0)
public_suffix (>= 2.0.2, < 5.0)
colorator (1.1.0)
concurrent-ruby (1.1.7)
concurrent-ruby (1.1.9)
em-websocket (0.5.2)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0.6.0)
ethon (0.12.0)
ffi (>= 1.3.0)
ethon (0.14.0)
ffi (>= 1.15.0)
eventmachine (1.2.7)
faraday (1.3.0)
faraday (1.8.0)
faraday-em_http (~> 1.0)
faraday-em_synchrony (~> 1.0)
faraday-excon (~> 1.1)
faraday-httpclient (~> 1.0.1)
faraday-net_http (~> 1.0)
faraday-net_http_persistent (~> 1.1)
faraday-patron (~> 1.0)
faraday-rack (~> 1.0)
multipart-post (>= 1.2, < 3)
ruby2_keywords
faraday-net_http (1.0.0)
ffi (1.14.2)
ruby2_keywords (>= 0.0.4)
faraday-em_http (1.0.0)
faraday-em_synchrony (1.0.0)
faraday-excon (1.1.0)
faraday-httpclient (1.0.1)
faraday-net_http (1.0.1)
faraday-net_http_persistent (1.2.0)
faraday-patron (1.0.0)
faraday-rack (1.0.0)
ffi (1.15.4)
forwardable-extended (2.6.0)
html-proofer (3.18.5)
html-proofer (3.19.2)
addressable (~> 2.3)
mercenary (~> 0.3)
nokogumbo (~> 2.0)
Expand All @@ -27,9 +41,9 @@ GEM
typhoeus (~> 1.3)
yell (~> 2.0)
http_parser.rb (0.6.0)
i18n (1.8.7)
i18n (1.8.10)
concurrent-ruby (~> 1.0)
jekyll (4.2.0)
jekyll (4.2.1)
addressable (~> 2.4)
colorator (~> 1.0)
em-websocket (~> 0.5)
Expand Down Expand Up @@ -64,37 +78,35 @@ GEM
jekyll-sitemap (~> 1.3)
jekyll-watch (2.2.1)
listen (~> 3.0)
kramdown (2.3.0)
kramdown (2.3.1)
rexml
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.3)
listen (3.4.0)
listen (3.7.0)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.4.0)
mini_portile2 (2.5.0)
multipart-post (2.1.1)
nokogiri (1.11.1)
mini_portile2 (~> 2.5.0)
nokogiri (1.12.5-x86_64-darwin)
racc (~> 1.4)
nokogumbo (2.0.4)
nokogumbo (2.0.5)
nokogiri (~> 1.8, >= 1.8.4)
octokit (4.20.0)
octokit (4.21.0)
faraday (>= 0.9)
sawyer (~> 0.8.0, >= 0.5.3)
parallel (1.20.1)
parallel (1.21.0)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (4.0.6)
racc (1.5.2)
rainbow (3.0.0)
rb-fsevent (0.10.4)
rb-fsevent (0.11.0)
rb-inotify (0.10.1)
ffi (~> 1.0)
rexml (3.2.4)
rouge (3.26.0)
ruby2_keywords (0.0.2)
rexml (3.2.5)
rouge (3.26.1)
ruby2_keywords (0.0.5)
safe_yaml (1.0.5)
sassc (2.4.0)
ffi (~> 1.9)
Expand All @@ -105,15 +117,15 @@ GEM
unicode-display_width (~> 1.1, >= 1.1.1)
typhoeus (1.4.0)
ethon (>= 0.9.0)
unicode-display_width (1.7.0)
unicode-display_width (1.8.0)
yell (2.2.2)

PLATFORMS
ruby
x86_64-darwin-19

DEPENDENCIES
html-proofer
jekyll-theme-so-simple

BUNDLED WITH
1.17.2
2.2.28
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ You can directly submit a pull request using the fork-and-pull workflow to add a

Pushing to the `build` branch lets you preview the build output using Netlify. You must log into Netlify to view the preview deploy.

Pushing to the `master` branch builds output to https://www.docslikecode.com using Netlify. Auto publishing is on as a setting in Netlify, so deploys from master are published automatically.
Pushing to the `main` branch builds output to https://www.docslikecode.com using Netlify. Auto publishing is on as a setting in Netlify, so deploys from `main` are published automatically.

## Theme Colophon
Theme courtesy of https://mmistakes.github.io/so-simple-theme/
Expand Down
2 changes: 1 addition & 1 deletion _data/authors.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

anne_gentle:
name: Anne Gentle
picture: http://docslikecode.com/images/anne_gentle.jpg
picture: https://docslikecode.com/images/anne_gentle.jpg
github: //github.com/annegentle
twitter: annegentle
bio: "Developer Experience Manager"
Expand Down
6 changes: 3 additions & 3 deletions _learn/01-sphinx-python-rtd.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ image:
caption: "Python and Sphinx"
---

Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version, and Python 2 is an unsupported Python version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from [ReStructured](http://docutils.sourceforge.net/rst.html) text files.
Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version, and Python 2 is an unsupported Python version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from [ReStructured](https://docutils.sourceforge.net/rst.html) text files.

In case you need both versions, refer to the [Downloads on the Python site](https://www.python.org/downloads/).

Expand Down Expand Up @@ -89,7 +89,7 @@ Most people use Virtual Environments because it's a recommended practice when wo

## Create a Basic Sphinx Project

You can also get familiar with [ReStructured text](http://docutils.sourceforge.net/docs/user/rst/quickstart.html), a plain text markup syntax system that you use to write content in Sphinx documentation. Sphinx can also accept [Markdown](https://commonmark.org/help/) files.
You can also get familiar with [ReStructured text](https://docutils.sourceforge.net/docs/user/rst/quickstart.html), a plain text markup syntax system that you use to write content in Sphinx documentation. Sphinx can also accept [Markdown](https://commonmark.org/help/) files.

1. Create a new directory for your project:
```
Expand Down Expand Up @@ -151,4 +151,4 @@ You can also get familiar with [ReStructured text](http://docutils.sourceforge.n
## Additional references

* [Sphinx Python Documentation Generator](https://www.sphinx-doc.org/en/stable/)
* [ReStructured text documentation](http://docutils.sourceforge.net/rst.html)
* [ReStructured text documentation](https://docutils.sourceforge.net/rst.html)
2 changes: 1 addition & 1 deletion _learn/05-cd-for-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,4 +116,4 @@ You can also deploy documentation sites using free hosting options as alternativ
## Additional references

* [TravisCI Core Concepts for Beginners](https://docs.travis-ci.com/user/for-beginners)
* [Convert AsciiDoc to HTML/PDF & publish to GitHub Pages with Travis CI and Asciidoctor Docker containers](http://mgreau.com/posts/2016/03/28/asciidoc-to-gh-pages-with-travis-ci-docker-asciidoctor.html)
* [Convert AsciiDoc to HTML/PDF & publish to GitHub Pages with Travis CI and Asciidoctor Docker containers](https://mgreau.com/posts/2016/03/28/asciidoc-to-gh-pages-with-travis-ci-docker-asciidoctor.html)
2 changes: 1 addition & 1 deletion _learn/11-print-pdf-epub-output.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ How difficult or straightforward is it to create a print or PDF format? You may

### Jekyll options

In the Jekyll Documentation Theme site, Tom Johnson suggests buying a license for Prince XML ($500) in order to create print-ready PDF files with the [Jekyll Documentation Theme](https://idratherbewriting.com/documentation-theme-jekyll/). The PDF layout and styles are set using CSS. Considering that the only gem solution, [jekyll-pdf](https://github.com/abeMedia/jekyll-pdf), makes PDF files of single pages rather than a collection, the third-party solution is probably the way to go. You could look into the [Open-Publisher](https://github.com/chrisanthropic/Open-Publisher) project, which is using Jekyll to create outputs that can be used as Pandoc inputs. [Pandoc](http://pandoc.org/) is a super handy conversion tool that can convert many formats to other formats, and has templating capabilities that can help.
In the Jekyll Documentation Theme site, Tom Johnson suggests buying a license for Prince XML ($500) in order to create print-ready PDF files with the [Jekyll Documentation Theme](https://idratherbewriting.com/documentation-theme-jekyll/). The PDF layout and styles are set using CSS. Considering that the only gem solution, [jekyll-pdf](https://github.com/abeMedia/jekyll-pdf), makes PDF files of single pages rather than a collection, the third-party solution is probably the way to go. You could look into the [Open-Publisher](https://github.com/chrisanthropic/Open-Publisher) project, which is using Jekyll to create outputs that can be used as Pandoc inputs. [Pandoc](https://pandoc.org/) is a super handy conversion tool that can convert many formats to other formats, and has templating capabilities that can help.

### Sphinx options

Expand Down
2 changes: 1 addition & 1 deletion _posts/articles/2016-11-26-remodel-your-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Here are some resources to get your first punch in that punch list:

* Using Python Sphinx? The OpenStack docs theme has some Javascript you could re-use to pre-populate an Issue template so the reporter sends the page URL, the source URL, the git SHA of the commit for that version of the page, and the release version value. See this [docs.js snippet](https://github.com/openstack/openstackdocstheme/blob/master/openstackdocstheme/theme/openstackdocs/static/js/docs.js#L119).
* Using a private repo for docs, but want to track bugs publicly? Use [Issues-only Access Permissions](https://help.github.com/articles/issues-only-access-permissions/).
* Want to add a bit of code to pre-create Issues to use as comments on every page? Free yourself from Disqus comments. Try this [set of tips and sample code in a blog post](http://zpbappi.com/jekyll-with-tags-archive-and-comments-in-github-pages/).
* Want to add a bit of code to pre-create Issues to use as comments on every page? Free yourself from Disqus comments. Try this [set of tips and sample code in a blog post](https://zpbappi.com/jekyll-with-tags-archive-and-comments-in-github-pages/).


{% include sign-up.html %}
2 changes: 1 addition & 1 deletion _posts/articles/2017-04-04-balsamiq-case-study-part-1.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ For the next update to our docs, we decided that we needed to finally address th

But, of course, we didn't want to maintain seven copies of each article. We wanted to be able to write the docs once and have them show up across multiple versions.

A simple solution, I suppose, would have been to switch from Markdown to a file format that supports including content from one file in another (like [reStructuredText](http://docutils.sourceforge.net/rst.html) or [AsciiDoc](http://asciidoc.org/)). **But, I'm stubborn** (and Hugo doesn't support them well). I like how simple Markdown is and I wanted to see if we could achieve what we wanted without abandoning it.
A simple solution, I suppose, would have been to switch from Markdown to a file format that supports including content from one file in another (like [reStructuredText](https://docutils.sourceforge.net/rst.html) or [AsciiDoc](https://asciidoc.org/)). **But, I'm stubborn** (and Hugo doesn't support them well). I like how simple Markdown is and I wanted to see if we could achieve what we wanted without abandoning it.

I enlisted the help of our resident [Go](https://golang.org/) expert, [Luis](https://balsamiq.com/company/#luis), and he wrote some code to do just what we wanted. This code inside one of the Hugo templates allowed us to put help files in two hidden folders (called "\_v2" and "\_v3") that would get injected into files across multiple documentation folders each time the site was generated. The end result was that users could now find the information where they expected to find it.

Expand Down
10 changes: 5 additions & 5 deletions _posts/articles/2017-04-09-balsamiq-case-study-part-2.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,16 +31,16 @@ But it can be distracting to read an article when there's an endlessly-looping a

I came across several sites that gave users an option to play the animated GIF when they clicked on it and I thought that would be great for our docs.

I found a great jquery plugin that I wanted to use called [**gifplayer**](http://rubentd.com/gifplayer/).
I found a great jquery plugin that I wanted to use called [**gifplayer**](https://rubentd.com/gifplayer/).

[![You know you want to click](https://media.balsamiq.com/images/docslikecode/gifplayer.png)](http://rubentd.com/gifplayer/).
[![You know you want to click](https://media.balsamiq.com/images/docslikecode/gifplayer.png)](https://rubentd.com/gifplayer/).

There was just one problem. Markdown. Again.

Triggering the gifplayer code is as easy as adding a CSS class to an image. Like this:

```html
<img class="gif" src="http://rubentd.com/img/banana.png">
<img class="gif" src="https://rubentd.com/img/banana.png">
```

But native Markdown doesn't support adding CSS. Of course, Markdown *does* support inline HTML, and we *could* have just written HTML whenever we wanted to add an animated GIF. But, again, **I'm stubborn**. I like my Markdown to be clean. I didn't want to go down a slippery slope of adding special cases for departing from pure Markdown.
Expand All @@ -60,11 +60,11 @@ Like this:
So, now, if we write:

```markdown
![gif](http://rubentd.com/img/banana.png)
![gif](https://rubentd.com/img/banana.png)
```
it triggers the gifplayer script!

![party](http://rubentd.com/img/banana.gif)
![party](https://rubentd.com/img/banana.gif)

Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. You can see the pause/play solution in action on our Balsamiq article on [common workarounds](https://support.balsamiq.com/tutorials/workarounds/#link-to-alternates).

Expand Down
6 changes: 3 additions & 3 deletions _posts/articles/2017-04-15-balsamiq-case-study-part-3.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ A big ol' list of links. A wall of text. It's a very different feel from the pag

It's clear to me that this page is automatically generated by some kind of content management system (CMS) template. Designers for pages like this usually cede control of the placement of the articles to the CMS, because they don't want to have to manually update it every time a new article is added.

They're limited because they don't know how many articles there will be in each category, so most sites just end up creating a simple list, perhaps in sub-categories. Even awesome documentation sites like [Mailchimp](http://kb.mailchimp.com/) and [Zapier](https://zapier.com/help/) do this once you go beyond the first level.
They're limited because they don't know how many articles there will be in each category, so most sites just end up creating a simple list, perhaps in sub-categories. Even awesome documentation sites like [Mailchimp](https://kb.mailchimp.com/) and [Zapier](https://zapier.com/help/) do this once you go beyond the first level.

And this is exactly what we do on our documentation site within each product category currently:

Expand All @@ -51,7 +51,7 @@ It feels more like a documentation site landing page, right? It has a featured a

I'll start by explaining the "Everything Else..." section at the bottom and what makes it different from our previous version.

The links there are automatically placed by Hugo and styled using the [Bootstrap List group](http://getbootstrap.com/components/#list-group) component. That part is pretty easy. The challenge was putting them in columns and making sure that the columns were equal heights, regardless of how many articles there were.
The links there are automatically placed by Hugo and styled using the [Bootstrap List group](https://getbootstrap.com/components/#list-group) component. That part is pretty easy. The challenge was putting them in columns and making sure that the columns were equal heights, regardless of how many articles there were.

Here's the code I wrote inside the Hugo template to define some variables to use further down in the code:

Expand Down Expand Up @@ -104,7 +104,7 @@ I wanted different images for each of the featured articles, but I just didn't l

{% raw %}
```html
<img src="http://media.balsamiq.com/img/support/docs/m4d/b3/toc-button-{{ .File.BaseFileName }}.svg">
<img src="https://media.balsamiq.com/img/support/docs/m4d/b3/toc-button-{{ .File.BaseFileName }}.svg">
```
{% endraw %}

Expand Down
6 changes: 3 additions & 3 deletions _posts/articles/2017-06-03-api-docs-with-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,11 +104,11 @@ namespace LinkInterface
}
```

After enabling these options, I *could* include code that enables the Swagger UI, but that interface looks a bit outdated. Also, I want to incorporate additional documentation written in Markdown, which the Swagger UI does not support. After reading online forums and posting questions to the [Write The Docs channel on Slack](http://www.writethedocs.org/slack/), I discovered DapperDox.
After enabling these options, I *could* include code that enables the Swagger UI, but that interface looks a bit outdated. Also, I want to incorporate additional documentation written in Markdown, which the Swagger UI does not support. After reading online forums and posting questions to the [Write The Docs channel on Slack](https://www.writethedocs.org/slack/), I discovered DapperDox.

## Using DapperDox

[DapperDox](http://dapperdox.io/) is an open source documentation framework for OpenAPI specifications. Instead of having Swashbuckle publish our API specification in the Swagger UI, I added the following code to the `Startup.cs` file. This code writes the Swagger specification to a `swagger.json` file.
[DapperDox](https://dapperdox.io/) is an open source documentation framework for OpenAPI specifications. Instead of having Swashbuckle publish our API specification in the Swagger UI, I added the following code to the `Startup.cs` file. This code writes the Swagger specification to a `swagger.json` file.

```csharp
System.IO.StreamWriter file = new System.IO.StreamWriter("swagger.json");
Expand All @@ -118,7 +118,7 @@ After enabling these options, I *could* include code that enables the Swagger UI

DapperDox reads this file and displays it in its own UI. I installed DapperDox and pointed it at my `swagger.json` file, and saw nothing but error messages in my command prompt.

Reading through the [DapperDox documentation](http://dapperdox.io/docs/spec-resource-definitions), I discovered that *"When specifying a resource schema object...DapperDox requires that the optional schema object title member is present."* This requirement was problematic, because Swashbuckle does not include a method for adding members to a schema in the generated `swagger.json` file. Additionally, it took some tinkering in the code for me to realize that the missing title member on the `definitions` model is what caused DapperDox to break.
Reading through the [DapperDox documentation](https://dapperdox.io/docs/spec-resource-definitions), I discovered that *"When specifying a resource schema object...DapperDox requires that the optional schema object title member is present."* This requirement was problematic, because Swashbuckle does not include a method for adding members to a schema in the generated `swagger.json` file. Additionally, it took some tinkering in the code for me to realize that the missing title member on the `definitions` model is what caused DapperDox to break.

## Fixing the output

Expand Down
Loading