ampersandjs / ampersandjs.com Goto Github PK

View Code? Open in Web Editor NEW

51.0 12.0 40.0 4.24 MB

The documentation site for ampersand.js

Home Page: http://ampersandjs.com

License: MIT License

HTML 55.80% Makefile 0.20% JavaScript 3.56% CSS 40.45%

ampersandjs.com's Introduction

Documentation site for ampersand.js

This generates the static site that lives here: http://ampersandjs.com/

How it works

The dynamic portions of the site are pulled down from The Internet™.

Specifically, we use module-details to fetch and parse complete info about a module from the npm registry.

The specific modules that get include listed and read from the package.json file in this repository.

As of this writing the relevant portion looks like this:

  ...
  "coreModules": [
    "ampersand",
    "ampersand-state",
    "ampersand-model",
    "ampersand-collection",
    "ampersand-rest-collection",
    "ampersand-view",
    "ampersand-view-switcher",
    "ampersand-router"
  ],
  "formModules": [
    "ampersand-form-view",
    "ampersand-input-view",
    "ampersand-checkbox-view",
    "ampersand-array-input-view",
    "ampersand-select-view"
  ],
  "featuredModules": [
    "bows",
    "emoji-images",
    "getusermedia"
  ],
  ...

The core and form modules are all fetched and dates compared to figure out which are in fact, the most "recent" for use in the home page "recently released" section.

The featured modules are grabbed and rendered in order listed in the "featuredModules" section.

So, updating "recent" doesn't require anything other than running the build script.

Updating featured, just requires picking 3 modules, they will be shown in the order they're listed.

The "docs" pages

These are built entirely from README.md files of the listed projects. They're run through a filter that removes hidden sections (such as "browser support" and "license"), and we also remove anything in between HTML comments in README's that look like this:

<!-- starthide -->
This text will not show up in generated docs
<!-- endhide -->

It's then converted to HTML and rendered using the jade templates.

Perhaps a bit convoluted, but works well enough.

The "learn" pages

These are all in markdown in the learn_markdown directory. There's a bit of metadata at the top.

This is the page title (used to generate what the nav calls it) and an order value that will be used to sort them all.

These don't have to be sequential and nothing will blow up if there are two that are the same or whatnot, they're simply run through a sorter that uses that value to attempt to sort them.

Adding a video

To add a video embed from Vimeo or YouTube, please wrap the iframe with a div.video-container.

Be sure the iframe does not have a set width or height.

Running that fabled "build" script

npm run build

Using something like http-server from npm will make working on the docs a bit easier, because links will work properly.

install it like so:

npm i -g http-server

There's a quick and dirty -w option that will rebuild if anything changes:

npm run build -w

So you can have that in one terminal tab, and just run http-server in the root project directory in another tab and you're up and running.

ampersandjs.com's People

Contributors

Stargazers

Watchers

Forkers

bentleyjensen jasonrhodes zefhemel hipsterbrown sdepold tswicegood alexfreska jackboberg rakesh-mohanta kahlil jgillich leksa cobookman jrmyio passcod alappe edull24 jeffjewiss dminkovsky brianshumate tzmanics tschaub mattlowe airandfingers mikehedman rtorr drewloomer joerter mrmikealexander e2jk gsf ratnesh-github gyaresu tragiclifestories jennwrites jameslinus spencerbyw 0xffffe001 throwoutofcoffeeexception

ampersandjs.com's Issues

No docs on state.collections

state.collections is only being told about here: http://ampersandjs.com/learn/state

The http://ampersandjs.com/docs itself do not contain anything about it.

Code highlighting is missing in a doc section

In this section of the docs: http://ampersandjs.com/docs#ampersand-view-render
the code highlighting is not working. When you look at the code you can see that the code is not wrapped with the correct classes. It rather looks like it has been wrapped with CSS classes for HTML code.

Add guide page to document spa animation.

Basically I couldn't find a good example of how to implement page to page transitions- preferably with css 3.

Determine how "Useful Modules" section will generate on homepage

How should these modules be chosen and are they manually or dynamically added?

Add "learn" page about jQuery

Responsive styles

Fix logo wonk in IE

Contribute.md for code

There is a contribute.md for docs, which is great. There needs to be one for the code itself, just one for the whole org hopefully. Each repo can have a contribute.md that links to the authoritative one. A link to the authoritative contribute.md should also be added to http://ampersandjs.com/contribute in the 'How to contribute' section.

Weird layout thing on shorter pages

note the grey border not going all the way to the bottom and the left nav hanging over.

Separate CSS and Stylus folders

What I've started doing (and I think it should be standardized) is separating CSS and Stylus folders. So, in CSS folder we only have:

normalize.min.css
main.min.css

And styl folder in public/ has all the stylus files and main.styl.

Docs titles are a bit broken in some places:

Seems that consecutive headers get collapsed onto one line because: display: inline-block:

CLI Tool Documentation

We should indicate which pieces/modules are put in place when building out an app stub with the CLI tool. Currently using it to build out an app, and noticing that I'm not sure whether or not I need to manually include -rest-collection, etc.

Make docs pages left-hand navigation fixed

Two scrollable panes, please!

docs -- minor error in require statement

On the first line of the file client/some-other-file.js in the guide http://ampersandjs.com/learn/transitioning-from-backbone

the require statement is
var MyModel = require('./models/model');
When it seems like it should be
var MyModel = require('./models/my-model');

This may have been intended to be implied, in which case never mind!

We actually support other browsers besides IE9+

The section of the site that says "Unapologetically supporting only IE9+." could probably be a little more explicit about what is supported so it doesn't sound like this is an IE-only framework.

Broken Link on Transitioning from Backbone

There is a link to "view guide" aka 'fetching-data-for-views' but no such route / markdown file exists.

Add "learn" page for differences between prop type `state` and `children` in ampersand-state

I think a better guide would have prevented this confusion: AmpersandJS/ampersand-state#31

Do we need a 404 page?

Markup and styling for Contribute page

Should include:

blurb about how to contribute, decisions that were made about the code base
core team (with images, profile links pulled from GitHub ideally)

Nice to have:

full list of all contributors (with images, profile links pulled from GitHub)

Add additional content to home page

Including:

Projects using Ampersand: Talky, OTalk, &! (http://docs.humanjavascript.com/#-examples for reference)
header illustration

Make it obvious that "Find Modules" link in main nav takes you elsewhere

Scroll bar issue reported by twitter user: https://twitter.com/distilledhype/status/484283104736329728

Could you look into this, Lynn? I'm guessing it's on windows, i'm not seeing it in Chrome/FF/Opera on my mac.

Review nitpicks

Homepage

review intro and description, maybe borrow from blog post?
"offline-first friendly" - what does this mean?
github link on emoji-images broken

docs

needs a good view bindings reference

Learn

fix titles/slugs
fix order of posts
finish
state: "da shiznit?"
forms: "Then, in a page you might use the form as follows:" this example needs to show the model being passed into the form view
forms: "the ampersand-cli**'s** at a model file"
view conventions - should list the conventions in words as well as code
jquery: I don't think replacing ampersand-sync in "browser" actually works, since it'd be a sub depedency.

Contribute

Ubersicht link should not include closed issues: http://espy.github.io/ubersicht/?showOpen=true&showClosed=false&showCommented=true&showUncommented=true&last24Hours=false&repos=null&labels=null&milestones=null&usernames=null#ampersandjs

General

add license files
fix tools.ampersandjs url
fix twitter avatar
follow some people on twitter who aren't the kardashians

"learn" pages

add active states for navigation

Guide Typos

Hey Ampersand,

Been going through the guides and noticed few paltry errors. Crowd sourcing the editing for y'all by letting no iteration of the experience go wasted...

quick-start-guide

Install the ampersand command line and running by running this in a terminal:

... should read ...

Install the ampersand command line by running this in a terminal:

npm-browserify-and-modules

browserify helps you bundle your application that uses commonjs modules up into a single JavaScript file that you can use in your application in the browser.

... is a run on sentence.

Put together the flow of creating a very simple web application with these tools might look something like this:

... needs a comma.

transitioning-from-backbone

In addition, just by following a few conventions, you can even have those view still play nicely with other views.

Views should be plural.

state

Well, as we said there's a huge amount of code that you write in a project really just describes and tracks relationships between values.

... need to add a that in there.

So, say you have a more "expensive" computation for model.

... for a model? Next sentence is a bit of a run on too...

Each state object you define will have and extend method on the constructor.

Extra 'd' added to make that 'an' and 'and'.

In addition, since it's a child that event propagates up.

... a bit cumbersome. Might need another comma at the risk of splicing.

That's all I'm going to read today. Maybe I'll come back and edit this when I continue if I find anything else.

Regards,
Judd

Nested and recursion data

Does ampersand support complex data types and relations (that backbone-relation and backbone-association works with)?

Critical: view.props is missing in docs

Wow, i was completely unaware views can hold props/derived too. That changes the way you build your models a lot!

I think it should be added to the docs asap!

(I'm unaware if "session" is supported too)

Add link icon to docs section titles

Separate CSS and Stylus folders

What I've started doing (and I think it should be standardized) is separating CSS and Stylus folders. So, in CSS folder we only have:

normalize.min.css
main.min.css

And styl folder in static/ has all the stylus files and main.styl. For consistency sake we should also rename static to public, it's a bit confusing now - do you agree @HenrikJoreteg?

Weird layout on wide screens

People with retina MBPs here saw it, it looks fine on my Air, but you can see it by zooming out:

Standardize commenting

Let's standardize commenting. Every file should have a header like this:

/*--------------------------------------------------------------------
*
* BASE
*
--------------------------------------------------------------------*/

And sections for elements in single stylus file should have the following header:

//- Section/Module Name

main.styl should have proper sectioning and annotations, see here:

*--------------------------------------------------------------------
*
* project name
* optional version
*
* Designed and coded by @projectowner
* Maintained by &yet
* ❤︎ 
*
--------------------------------------------------------------------*/

The heart is optional ;)

Nice to have: Render contributors list from GitHub API

Needs:

Core team:

contributor username
contributor profile URL
contributor avatar

Other contributors:

contributor profile URL
contributor avatar

Events documentation

I think Events should be added to the documentation. The Backbone docs made it clear Backbone.Events is mixed into everything, and docs what it does clearly at the top.

It isn't 100% clear that things like model.once is supported in Ampersand.

If a person doesn't have Backbone experience wanted to use Ampersand, I doubt they will know the catalog of events that's available, along with methods like on, once, listenTo ...

Copy for "Contribute" page

pre and code elements force horizontal scroll bars

Hi,

pre and code elements force horizontal scroll bars because the CSS sets

overflow-x: scroll

on both.

I see it on Chrome on Mac.

This can be fixed by setting the property to auto so the scrollbars only show when appropriate.

Document properties derived from a child collection

There have been several issues lately of people wanting examples on how to derive properties based on data from a child collection. This should be documented somewhere like ampersand-state (and probably linked to from places like ampersand-collection)