Customization through user provided client scripts and stylesheets

[baoshan]

@zmaril kindly suggested if users could put the following folder structure in their repos, docas should be able to pick the JavaScripts and stylesheets up in the rendered web pages.

+ docas
  - css
    * page.css
    * jquery-ui.css
  - js
    * script.js
    * d3.v2.js

[baoshan]

Hi Zack,

Actually, you can embed custom scripts, stylesheets, and images as I do:

http://baoshan.github.com/docas/

It's not so common all generated documents will share the same set of resources. So specify them in the source file's comments may be more flexible.

What's your opinion on this? Could you help figure out a smooth workflow for designing interactive documentation?

Thanks.

[zmaril]

It is fairly common to include the same set of resources in generate documents. I would be including the same CSS every single time for all of the documentation. There has to be a way to always include the same files each time. Otherwise it will be too much hassle to add in custom css every time.

What do you mean by interactive documentation? If you can define that then you would be starting off well. You might want to look into how gh-pages displays pages. They use some ruby thing, maybe sinatra?, to display everything. If people could have a local copy of docas on their machines, they could compile everything there.

But if they had a local copy, they wouldn't need docas.io as a service. Is this a potential business you want to pursue?

[baoshan]

I understand for your d3 tutorial, many pages share the same set of resources should be embedded in the rendered html files.

1. Do all your sources in the d3 repository require those stylesheets?
2. Will it be trouble if docas embedded your stylesheets and scripts in the sources which does not require them?

I just want to make sure for your scenario, treat all documents the same way and inject the stylesheets and scripts in the docas folder will not bring too much side effects. Could please confirm the above questions?

What I mean interactive documentation is not simple presentation of sources and explanations. I'm not to care about the technologies there, whether it be (Frank) Sinatra or Zappa :) I'm defining the workflow for designing interactive documents:

1. What creative people want.
2. How to make their work easier, I mean boost the productivity by not introducing any inconvenience. For example, people should be able to work easily on their development machine, and publish easily.

For your last question, it's more important for me to find the optimal solution for the correct question than doing business. I want to make docas useful, enjoyable.

Thanks!

[zmaril]

1. All of my sources in d3 would require those stylesheets.
2. No, the scripts would not be a problem.

Okay. Then the workflow should be something like the following:

In the command line, issue a command that runs a server that serves the
complied html files automatically.

Example:
cd d3
docas_dev

Now, open up your favorite editor and change one of the files in the d3
directory. Save the file. Reload the relevant webpage and watch it be
already be updated with the changes. This happens because the program that
is acting as a server is watching the d3 folder for any file that changes.
Whenever a file changes, "docas_dev" recompiles the html file and serves
the new from the server.

That would be a wonderful way to start.

On Thu, May 24, 2012 at 11:47 PM, baoshan <
reply@reply.github.com

wrote:

I understand for your d3 tutorial, many pages share the same set of
resources should be embedded in the rendered html files.

1. Do all your sources in the d3 repository require those stylesheets?
2. Will it be trouble if docas embedded your stylesheets and scripts in
   the sources which does not require them?

I just want to make sure for your scenario, treat all documents the same
way and inject the stylesheets and scripts in the docas folder will not
bring too much side effects. Could please confirm the above questions?

What I mean interactive documentation is not simple presentation of
sources and explanations. I'm not to care about the technologies there,
whether it be (Frank) Sinatra or Zappa :) I'm defining the workflow for
designing interactive documents:

1. What creative people want.
2. How to make their work easier, I mean boost the productivity by not
   introducing any inconvenience. For example, people should be able to work
   easily on their development machine, and publish easily.

For your last question, it's more important to find the preferred solution
for the correct question for me. I want to make docas useful, enjoyable.

Thanks!

---

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

[baoshan]

docas has experimental support for embedding user specified JavaScripts and Stylesheets in the docas folder through a configuration file named .docas.conf in the root directory of the master branch.

Below example show a sample pattern which instruct docas to embed scripts and stylesheets in the rendered html.

# Specify the patterns to embedded JavaScript files.
# JavaScript files are embedded immediately before the closing </body> tag.
#
# * Keys are used to match the full path of sources.
# * Values are JavaScripts need be embedded, paths are relative to docas folder.
page_javascripts:
  examples/*: examples.js

# Specify the patterns to embedded stylesheet files.
# Stylesheet files are embedded immediately after the beginning <head> tag.
#
# * Keys are used to match the full path of sources.
# * Values are stylesheets need be embedded, paths are relative to docas folder.
page_stylesheets:
  *: common.css
  examples/*: examples.css

[baoshan]

It would be interesting if d3 tutorial come with live examples. I would like to work with you to make that happen. Wish I could learn d3 following the tutorial!

Please re-open the issue if that's not what you want or the approach is not acceptable. And please provide feedbacks for improvement.

Currently, I'm working for a performance boost. My goal is to finish the new compilation of the d3 tutorial in one or two minutes.

[zmaril]

Great! I will take a stab at doing some remodeling this week with CSS.

Live examples: one of the first things I thought of was live examples. I am
still rolling around how to do it. Possibly I am thinking of embedding the
results form js fiddles. Not sure though. Need to tackle the css style and
writing of the comments first.
-Zack

On Sat, May 26, 2012 at 11:55 AM, baoshan <
reply@reply.github.com

wrote:

It would be interesting if d3 tutorial come with live examples. I
would like to work with you to make that happen. Wish I could learn d3
following the tutorial!

---

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

[zmaril]

Just added in d3.js to every page. Awesome.

Are you sure you don't want the docas folder to be named .docas? And why not put .docas.conf in .docas as just conf?

[zmaril]

Also, maybe do a regular expression for file paths.

Something like:

page_javascripts:
  *: d3.v2.min.js
  /([.]+)\.html : (regex_matches)-> "#{regex_matches[1]}.js"

This would make interactive examples a hundred times easier to create.

[baoshan]

Great idea to re-name docas to .docas. But I'm afraid it'll be re-named to docas in the gh-pages branch. Since the nginx server used to serve static files is configured to not serve files in folders start with a dot.

So I'll re-name docas to .docas and place the conf there later.

About the regular expression pattern, it's also awesome and simple. I'll try to enhance the feature and when I'm done, I'll provide examples.

Thanks.

[zmaril]

Cool. I've had to unwatch this project because you are doing so many pushes
and pulls on it. You dominated my github news feed. Good job so far ;)
-Zack
On Tue, Jun 12, 2012 at 12:07 AM, baoshan <
reply@reply.github.com

wrote:

Great idea to re-name docas to .docas. But I'm afraid it'll be
re-named to docas in the gh-pages branch. Since the nginx server used
to serve static files is configured to not serve files in folders start
with a dot.

So I'll re-name docas to .docas and place the conf there later.

About the regular expression pattern, it's also awesome and simple. I'll
try to enhance the feature and when I'm done, I'll provide examples.

Thanks.

---

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