Documentation spike

[myronmarston]

I've started trying to get docs added to the site. While we don't need docs before launching the new site, I'd kinda like docs on the site before we make a big announcement about it or at least before 3.2 is released.

To generate these docs, here's what I ran from an rspec-core checkout:

$ bundle exec yard doc --no-cache -o ../rspec.github.io/source/documentation/3.2/rspec-core

(Note that rspec.github.io is in a sibling directory here).

This generated all the necessary files, but I'm seeing some issues.

First, if I go to http://localhost:4567/documentation/3.2/rspec-core, it's lacking all css/js assets:

...but if I go to http://localhost:4567/documentation/3.2/rspec-core/index.html, it does have the css/js assets:

I don't understand why the /index.html is needed. (Obviously, I don't understand middleman well yet...)

On that apparently working page, I can't actually navigate to any of the docs -- it can't find the index files:

The result is the same for "Method List" and "File List".

Looking at the build directory, I notice I'm not seeing any of these files being copied there. I suspect that's the culprit.

@JonRowe, do you have any ideas how to get this to work?

[JonRowe]

I believe this is due to using relative paths for the assets, I was actually pondering hosting the documentation in a separate repo and use github pages for that again, the benefit would be that it'd be self contained and could use any static generation it liked.

[myronmarston]

I believe this is due to using relative paths for the assets

The produced output (including assets) work fine as static HTML when served normally. I see two reasons for the problems:

• For the first problem, our activate :directory_indexes config causes .../docs/3.1/rspec-core/index.html to be served at the URL .../docs/3.1/rspec-core but the asset paths were designed to be relative to the index.html version of the URL.
• For the 2nd problem (missing files), from what I saw, only the root index.html file was copied to the build directory. Do you know what determines if middleman copies a file from source to destination?

I was actually pondering hosting the documentation in a separate repo and use github pages for that again, the benefit would be that it'd be self contained and could use any static generation it liked.

Interesting idea. I'd prefer not to go that direction for a couple reasons:

• Longer term I expect we'll probably want to apply some kind of transformation to these files....e.g. find a way to apply our chrome to the doc pages so the header links aren't lost. Also, we could do things like provide version links to jump between RSpec versions.
• I'd rather not have to deal with deploying two different sites for what we conceptually think of as 1 site.
• You mention using any static generator we like...but I'd prefer the simplicity of one set of conventions using one static generator.

I'm guessing we might have to write a middleman plugin or extension to get this to work right with middleman? Or maybe the files just need to be saved as html.erb or something similar that it'll pick up, process and copy to the build directory? (Using erb would also allow us to do a layout thing). I bet it would be simple with nokogiri to pull out the content of each page from the layout part and save it as an erb file. I may try that.

If doing this in the same repo with middleman proves too difficult I'm up for trying your separate repo thing but I'd prefer not to go there yet.

[JonRowe]

The :directory_indexes option messes with the folders to produce nice urls, this is deliberate, e.g. /about.html becomes /about/index.html and thus accessible as /about. You can opt out of this, so maybe try that with docs? See http://middlemanapp.com/basics/pretty-urls/#opt-out (I think if you glob the docs path that will work?)

[myronmarston]

The opt-out thing appears to work. There's still a couple minor problems:

• If you visit ..../rspec-core/ rather than .../rspec-core/index.html, it looks broken because the asset paths are relative to the latter URL. As long as we link to the latter form, things should work OK, but users can still visit the former path, expecting it to work (given that none of the rest of the site uses the index.html convention...) and see the problem.
• Many other pages have a .html extension, which is a different convention from the rest of the site.

[JonRowe]

To fix this we need to add our own copies of the assets and rewrite the path to be absolute, we could possibly then renable directory indexes to fix the second problem

[myronmarston]

To fix this we need to add our own copies of the assets and rewrite the path to be absolute, we could possibly then renable directory indexes to fix the second problem

I don't quite follow. Want to take spike something out to demonstrate what you mean?

[JonRowe]

So I was going to take a look at this, but I cant replicate your lack of styles, /docs/3.2/rspec-core/ works just as well as /docs/3.2/rspec-core/index.html for me, I have done a bundle update recently though

[myronmarston]

You're right, /docs/3.2/rspec-core/ works. It's /docs/3.2/rspec-core (no trailing slash) that has problems. I misspoke earlier, sorry.

[myronmarston]

@JonRowe -- are you planning to look into this some more (bearing in mind the problem is with /docs/3.2/rspec-core, not /docs/3.2/rspec-core/)?

[JonRowe]

Yes, I'm looking at the yard template customising system. We should be able to override the generation of the assets to prevent this issue.

[myronmarston]

Sounds promising. Long term, I'd love it if our docs included the chrome of the rest of the site so that it "fits in" with the look and feel with the rest of the site. Not necessary for this iteration, but while you're playing around with the yard templating system, maybe you can keep your eyes out for a way of using YARD's system for that purpose?

[JonRowe]

Yeah that's the aim :)

[JonRowe]

I have this working now, generating docs with assets hosted in the main styles directory.

[JonRowe]

You have to run bundle exec yard --plugin rspec-docs-template --output-dir ../rspec-website/source/docs/3.2/rspec-core/ with a gem 'yard-rspec-docs-template', path: '../rspec-website' entry in your bundle to generate fresh docs.

I also have the template bits to edit the header, but I've not got the css right yet

[myronmarston]

Thanks, @JonRowe. This seems to have broken the Class List/Method List/File List drop downs:

Here's what it looks like at /docs/3.2/rspec-core:

At /docs/3.2/rspec-core/ it finds the files but they look unstyled:

Compare that to what we had before (when at /docs/3.2/rspec-core/):

[JonRowe]

Looks like they're using relative urls too, I'll look into it.

[JonRowe]

Ok, so this turns out to be an issue with middleman server it's not present in the real deployed docs because it enforces the trailing slash (as I'd expect from a static web server) see: http://rspec.github.io/documentation/3.2/rspec-core

[JonRowe]

(I've currently deployed this branch so I could check it, it'll be overwritten if someone deploys source)

[mootpointer]

@JonRowe :D

On Wed, Dec 17, 2014 at 10:43 AM, Jon Rowe [email protected]
wrote:

Ok, so this turns out to be an issue with middleman server it's not present in the real deployed docs because it enforces the trailing slash (as I'd expect from a static web server) see: http://rspec.github.io/documentation/3.2/rspec-core

Reply to this email directly or view it on GitHub:
#20 (comment)

[JonRowe]

This is the command used to generate docs now BTW:

bundle exec yard --plugin rspec-docs-template --output-dir ../rspec-website/source/documentation/3.2/rspec-core/

(edit: obviously the ../rspec-website path should be to your copy of the website)

Stills needs the website added as a gem to load the file, but I think that's ok, and we can use rspec-dev to automate this eventually.

[JonRowe]

Shout out to @mootpointer for help with that ;)

[myronmarston]

Cool, glad to hear it's not a real issue, although I'm a bit confused about why middleman server works differently. Is there anything we can do about that?

Anyhow, as far as getting this ready to merge and release, here's what I'm thinking is left...

• Add docs for all our gems (core, expectations, mocks, rails) for 2.14, 2.99, 3.0, 3.1 and 3.2. We could potentially go back further but I think 2.14 is sufficient as a representative of 2.x versions before the 2.99 upgrade process.
• Update the /documentation page to provide links to all the hosted docs.

And then as you said, we can later automate this some more.

[JonRowe]

Cool, glad to hear it's not a real issue, although I'm a bit confused about why middleman server works differently. Is there anything we can do about that?

It's a sinatra thing, we could work out how to force redirects for it but TBH I don't think it's worth it, I've made the links add a / so when clicking around it'll work fine.

All the docs are now up so merging and we can refine the links further if you want.

[myronmarston]

Why no 3.0 or 3.1 docs?

[JonRowe]

Oh because I missed those in your comment

[JonRowe]

I'll add them later

[JonRowe]

(incoming)

[JonRowe]

See #34