ofDocs - alternative documentation, examples, code browser

Hello, hope everyone is doing OK during this hard time and looking after yourselves and others.

I recently finished building an alternative docs browser - something that started off as Sunday procrastination (a way to more easily views docs and examples together, and avoid working on my own website), and since developed into a sort of hybrid markdown, code (w/ Nikola docs) and file structure viewer. I also added a simple file search (Alt + F), “See Also” links between files, and markdown editor.


ofDocs (static)

ofDocs (github)





Under the hood, the app is built with Nuxt, which is a Vue JS framework for rendering single-page apps both server and client-side, with the added benefit of having a static website generator.

When ran locally, the app mirrors file and folder structures defined in the docs.config.js file. An API middleware reads the files and folders into JSON and syntax-highlighted HTML, so that when navigating to a page Vue will request its own API (ie. ?as=json / ?as=raw) to render the view. Finally, when statically generated all of this is exported as a recursive HTML structure, that can be upload to a standard LAMP / FTP server or Github Pages.

What’s nifty about Nuxt is that it also combines server-side rendering and client-side rendering when statically generated. So when viewing the initial webpage, it’s already a raw HTML webpage (good for SEO, if that matters in this case) - and once the JS is loaded, will request subsequent pages asynchronously with Vue (where the API-generated JSON is embedded as a payload within the HTML).

In the static site the Edit button currently links to a readme, but when ran locally it will toggle a <textarea> that can be used to save changes directly to file via the API (for safety, this only works on .markdown files defined by docs.config.js).

Most <img> embeds should be fine - though there are some caveats such as trailing slashes changing relative <img> urls on the initial page load, or unusual asset locations - easily fixed by editing docs or swapping locations.

The ethos though has been to ideally not edit or change anything to fit the app, so that it just renders what’s already there. Conceivably it could also be used as a documentation / folder / code browser for anything you point it at - configurable via docs.config.js.

For the OF-specific rendering, RegEx is currently used to parse the Nikola formatted docs into lists of methods and variables, so they can be more cleanly rendered into menus (currently a method w/ documentation is labelled pink in the right-hand menu, and gray without).

Any feedback, bugs-found or ideas at this stage would be great. I’m also keen to know more about how Nikola is used to generate the documentation (something which I didn’t touch in the process), and whether that could be integrated or improved on.

Thanks, and keep well!

10 Likes

heyho autr,
this sounds interesting, i will have a closer look and give feedback.
there was a group at the ofcc in denver focussing on documentation. it think it makes sense to get aligned with them. @zach and @ayruos can probably tell you more about it.

@edapx had the working markdown examples.

@ayruos @thomasgeissl, the project started at Denver was called “focused reference”, and it was a subset of the OF documentation, improved in layout and, in general, clarity. The idea, at that time, was not to replace the actual ofDoc with that one, but to provide a short reference for beginners and educators, to facilitate the on-boarding process. Therefore I do not think that the two things can be “aligned”.

@zach was saying that he might have some budget to pay one of his students to finish it, but I do not know what’s the status on this front.

The project it is discontinued because of lack of participation. The last messages in the doc channel on slack are from months ago. I have collected all the docs produced at Denver and uploaded them on a private repository, inviting the person that were at Denver, but just 2 or 3 people opened it. I have added a couple of new pages for the 3D section. I do not think it make any sense to publish that repository unless that there are people that want to finish it.

Interesting - though I’m not a student paid to make this!

When learning I feel there is that first hurdle of getting oriented / learning the basics, after which you can self-learn. So when working something out I’d read introductory paragraphs from ofSite, view the methods in the header file, and examples for the implementation.

With a focussed reference it sounds like it might be reiterating the basics when what I’ve found helpful is contextualising the complexity with the simplicity in one place.

For example in the docs pages there are many internal / private or rarely used methods which is information-overload when working out the essentials.

So it may just be a case of sorting the information… which could be by public / private, or by flagging methods and variables (ie. key ones used in examples) as “the essentials”.

That way there isn’t a sort of entropy between “beginner docs” and “advanced docs” which is an ambiguous line to draw anyway.

At that juncture then maybe the focussed reference might fit. Similarly its possible to add ofBook and other ofSite learning guides into ofDocs, but this would need some tweaking - essentially making sure the folder structure is the URL structure and having assets referenced in the markdown file located in the same root.

With updating docs I imagine that can be a pretty thankless / boring task so anything to remove friction from that process was the purpose behind adding a Edit button to the doc pages … ie. if you see something missing then you don’t have to tab over to a text editor, find the file, scroll to line number (by which time you’ve forgotten what it was you were doing).

I also wrote some bits to grab the last git commit date for a file and add it to the doc page header but kept it out. After seeing so many “last updated 2016” tags it started to come off almost passive aggressive about out-of-date docs :sweat_smile:

It would be possible though to drill down a list of docs sorted by last updated - and this could be useful toward some communal effort to update docs. I was thinking something along the lines of: roll a dice = utilise a class, then update its doc page.