Comments (7)
This ticket is actually focused on a different aspect of "API Documentation" -- not the automatic generation of content based upon code, etc., but rather the organization and presentation of API documents to the end user/reader.
In other words, regardless of the internal mechanisms used to document actual code and transform that into documents, an over-arching organization of all the API docs we provide on docs.lfe.io needs to be addressed. The latest mockups for v3 of the site are exploring this organization.
from docs.
I've always been fond of Hackage and QuickDocs. Seems QuickDocs is offline at the moment (cached copy).
Hackage links into your dependencies documentation, it shows you the types and can even link images. Some folks even generate images using some sort of ascii->png tool and embed it into the docstring.
Having code samples in documentation is a huge win.
Maybe LFE should have it's own wrapper to EDoc? Maybe something new that gathers from the different docstrings and parses them into a nice format? Shipping with up-to-date docs (including dialyzer types annotations) should be encouraged.
from docs.
I've been looking at projects like Read The Docs (Sphinx-based, uses ReST instead of Markdown ... not good for us, but pretty good overall API docs site features) and I haven't yet found anything that really grabs me.
The Github Documentation site is actually the most impressive I've seen so far:
They blogged about how they're now supporting versioned docs (which we will need) with the latest Jekyll and the release of their new site: How GitHub uses GitHub to document GitHub. They've open-sourced their site here:
I'm going to try to get a copy of it running and see how we might adapt it for LFE. Our stuff is already in markdown (all the sites as well as all the Gitbooks), and we use Jekyll already for the docs site and the blog, so this might be the best place to start for now ...
from docs.
@arpunk: I've been thinking more about your example of http://quickdocs.org/ ... this is one facet of what I'd like for docs.lfe.io to provide. Maybe through a combination of:
- projects adding documentation metadata to a project file
- LFE projects generating their API docs with lodox and maybe user guides with Slate or some such.
- the software we use to generate docs.lfe.io could then check all the projects in a set "approved" (read: searched/known) Github orgs (e.g., lfe, lfex, lfe-rebar3, quasiquoting, etc.) and for all projects that have a configuration file with the appropriate project documentation metadata would then get included in a part of the docs.lfe.io site ... something very similar to what http://quickdocs.org/ is ...
from docs.
Something else that I've been looking at lately for higher-level project organization is the work that the OpenStack community has done with http://docs.openstack.org/ ... in particular the intuitively obvious category-level organization below the fold on that site (this ticket is exploring that work in the context of an LFE docs site: lfe-deprecated/docs3#2).
from docs.
The LFE compiler is soon to get a whole lot better at handling docs. We're going to write a beam chunk (for now) called "LDoc" with a property list of doc records, similar to the shape of Lodox data currently. I'm away from my keyboard now, but my get it wrapped up nicely as soon as tonight. The relevant issue is lfe/lfe#211.
from docs.
Calling this one done -- but feel free to add anything useful that you come across. This ticket will remain linked to others, and continue to provide the source of information needed to evaluate good examples.
from docs.
Related Issues (20)
- Update the LFE Style Guide HOT 1
- Deprecate style guide on site in favour the LFE Style Guide book HOT 1
- Infrastructure Updates
- Replaced bootstrap-sass with git submodule HOT 1
- Fix up SASS/CSS for Mobile HOT 1
- Add a file watcher HOT 3
- Recompile ErlyDTL files when they change HOT 1
- Recompile LFE files when they change HOT 1
- Update instructions with --depth option for clone HOT 1
- Support a watcher on Mac OS X
- Compile broken on Mac OS X when inotify support added HOT 2
- Build is failing on Travis CI HOT 1
- Consider testing on OS X as well as Linux on Travis CI HOT 4
- Hey, I was reading the docs and noticed a message about the site being rewritten (and asking for help)?
- "Watch LFE presentations" link is broken HOT 3
- Documentations/LFE book HOT 4
- Active works on LFE. HOT 2
- Unification of Disparate Content
- Revamp Old Content
- Create new community page(s)
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docs.