Surface DLR docs for deep linking

[zspitz]

I've written a Visual Studio custom debugging visualizer for expression trees (and other types in System.Linq.Expressions.Expression).

I would like to expose links to the documentation at https://github.com/IronLanguages/dlr/tree/master/Docs from within the visualizer's context menu, much like I already link to the standard Microsoft documentation. Specifically, to expr-tree-spec and dlr-overview. Currently, the files are stored as PDFs and Word documents, which means it's impossible to link within these files, only to the files themselves.

Are there any plans to move this documentation to Microsoft Docs? Or, perhaps to the wiki section on this repo? Or some other globally available host? Presumably it would be easier to work with these files in Markdown; I would be willing to carry out this conversion.

If the documentation is moved to the wiki, what guarantees would I have that the headings -- required for deep linking -- would remain the same?

[slozier]

This repo is no longer Microsoft owned so I have no idea about getting it on Microsoft Docs. Making it available on the wiki would be reasonable.

As for the headings remaining the same, if the docs are simply markdown versions of the original docs then I see no reason why any of it would change.

[zspitz]

I propose to do the following:

1. Save the documents as .docx
2. Use pandoc to convert the .docx files to markdown. Fiddling with some of the options gets me 99% of the way there. Commit. If someone else can later figure out how to get better output, they can redo this commit and apply later changes.
3. Some additional review and polish will be needed: e.g. linking to other DLR documents or MS documentation.
4. Generate the sidebar TOC from the various documents.

Is this a good plan? @slozier, do you have any other thoughts on this?

[slozier]

@zspitz Sounds like a plan.

[zspitz]

Well, it's been 2.5 months, and I think I've automated as much of the conversion as I can. (It's been an interesting journey -- along the way I developed a library for writing Pandoc filters in .NET languages, and the actual conversion source is here).

The result of the conversion is attached to this comment.

@slozier I think there are still some corrections to be taken care of. Among others, I think the entire section of the API reference for expression trees (and perhaps other documents) should be replaced with a link to the appropriate Microsoft documentation.

But if you feel the quality is good enough, would you consider putting this in its current state in the wiki? At least to check that internal links, sidebars, page headings all work.

I would be willing to carry out the editing I described above, but either 1. the wiki would have to be writable to everyone, or 2. I'd need write permissions on the repo. Per the GitHub docs:

You can edit wikis directly on GitHub, or you can edit wiki files locally. By default, only people with write access to your repository can make changes to wikis, although you can allow everyone on GitHub to contribute to a wiki in a public repository.

output.zip

[slozier]

Very nice. I tried loading the docs in the wiki but it doesn't seem to handle it very well, maybe I'm missing something. Perhaps another option would be to host it via GitHub Pages. Any thoughts?

[zspitz]

I wanted to preserve the numbering in the text, while keeping the numbers out of the hashtag document fragments. But the wiki system inserts user-content into the non-autogenerated ids.

I don't have any experience using GitHub Pages, but it looks like it would be a better option. I'm guessing I'd be able to fork the main repo, create the gh-pages branch in my fork, and then pass a PR to the main repo. I'll try this and let youn know what happens.

While it's possible to configure GitHub Pages to use the /docs folder in a repo, on any branch, the repo already has a Docs folder which stores the Word documents / PDF files.

[slozier]

While it's possible to configure GitHub Pages to use the /docs folder in a repo, on any branch, the repo already has a Docs folder which stores the Word documents / PDF files.

I had noticed that as well. We can move the doc/pdf files to another location. It could be a subfolder of docs and then be made available for download via a link in the markdown.

[zspitz]

The GitHub Pages on my fork can be seen here. The links between documents are working.

It seems a little plain. Do you have any suggested improvements?

[slozier]

It does seem a little plain, but we can probably make it a bit more colorful by adding a theme via _config.yml (looks like the GUI can also do it)? The navigation between sections of a document is a bit painful, but presumably it could be added after the fact (I assume themes support sidebars and such).

There's a typo in: "DLR Hostirng Spec"

[zspitz]

Thanks for the typo; I've corrected it. I've also reformatted the first-level headers in the TOC to a higher level, in order to emphasize them within the TOC.

If I understand correctly, putting the TOC in some kind of sidebar would involve customizing the layout. I'll look into it further next week. I suspect that some of the header titles are going to be too wide for a sidebar. Do you have any suggestions?

Also, at some point I think it appropriate to merge the docs from my fork into the main branch. When is the right time to do so?

[zspitz]

@slozier I've chosen a different Jekyll theme, with a built-in TOC mechanism, and I think it came out rather well (the link is the same as above). I'm going to start manual edits on the content.

[slozier]

@zspitz Looking nice indeed!