Documentation Improvements

[Alon Zakai]

Hi everyone,

We are planning to start an overhaul of the emscripten documentation soon, that is, of the contents of the wiki on github. One option might be to move to Jekyll, which is convenient as it has good github integration.

If you have any thoughts on the current docs and how they can be improved, let's discuss here.

- Alon

[Mark Callow]

I'll start with a few basic questions.

What do you see as the advantages of Jekyll vs. a wiki? Over the Github Wiki? Will we have to learn YAML (yet another markup language)?

I haven't looked at the documentation recently so I don't recall the issues I have had. I'll take another look.

Regards

    -Mark

--

注意：この電子メールには、株式会社エイチアイの機密情報が含まれている場合が有ります。正式なメール受信者では無い場合はメール複製、 再配信または情報の使用を固く禁じております。エラー、手違いでこのメールを受け取られましたら削除を行い配信者にご連絡をお願いいたし ます.

NOTE: This electronic mail message may contain confidential and privileged information from HI Corporation. If you are not the intended recipient, any disclosure, photocopying, distribution or use of the contents of the received information is prohibited. If you have received this e-mail in error, please notify the sender immediately and permanently delete this message and all related copies.

[Mark Callow]

On 19/06/2014 13:53, Mark Callow wrote:

Will we have to learn YAML (yet another markup language)?

It seems there may be something called YAML. I do not mean that language in particular.

[Bruce Mitchener]

I really like working with Sphinx and ReStructured Text: http://sphinx-doc.org/

I've used it (successfully) to produce thousands of pages of technical documentation, encompassing multiple books.  We publish these materials in HTML, PDF and ePub.  We've written our own extensions as needed and it has been pretty easy.

I can't say enough positive things about it and only have a few relatively minor complaints.

 - Bruce

[Alon Zakai]

Jekyll is popular in this space, and has good github pages integration support, so it seems like a good solution. It uses Markdown, same as the github wiki I think.

- Alon

--
You received this message because you are subscribed to the Google Groups "emscripten-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-disc...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Alon Zakai]

Sphinx sounds interesting, thanks. The export options in particular (PDF, ePub) are appealing.

- Alon

[Warren Seine]

If you like Sphinx, you should definitely have a look at ReadTheDocs. Basically, it's a platform for hosting documentation from Sphinx source files. The source of the documentation stays on GitHub and documentation is regenerated on commit hooks. It's quite popular in the Python community, though there's nothing specific to the language.

Of course, there's an export feature for PDF and ePub. Also, the default themes are nice enough to start with.

Cheers,

To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-discuss+unsub...@googlegroups.com.

[Trevor Linton]

I'd be happy to help. One aspect I think could use a very thorough once over is the emscripten.h C documentation, shouldn't be difficult bringing it to a wiki or jekyll.  Also, the emcc/em++ command line options, there are some options aren't documented (other than the paragraph found in the help). 

If there's anything you'd like me to take a pass at, let me know.

[Alon Zakai]

That's very interesting, thanks! We should look into that.

- Alon

To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-disc...@googlegroups.com.

[Alon Zakai]

Thanks, help is always welcome.

I guess the first question here is where to put the docs - we have emscripten.h docs inline, and I'm worried about copying it to another place without removing the original, to avoid duplication and one being out of date etc. So the question is, is comments in the source better than a separate doc? Comes down to what people prefer I guess. Thoughts?

- Alon

[Trevor Linton]

I'm not sure, it's unfortunately one of those problems i'm unsure if there's a complete solution to. The documentation is very complete in emscripten.h, i'm generally a fan of looking at things from users perspectives.  Most who are looking at documentation or have questions would first go to the documentation (at least that's my experience), generally someone pokes around at a header file as a last resort (at least thats just me).  In addition, jekyll and wiki's have the luxury of layout which allows you to add images, diagrams, links to other sources.  So, i'd say simple notes in the header that refer to the URL for the documentation and keep all the documentation in one place.

But that's just me.  

Let me know how you'd like help!

To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-discuss+unsub...@googlegroups.com.

[Mark Callow]

On 20/06/2014 03:35, Alon Zakai wrote:

Jekyll is popular in this space, and has good github pages integration support, so it seems like a good solution. It uses Markdown, same as the github wiki I think.

What I should have asked is what are the problems with the existing documentation are you trying to solve? How does Jekyll solve those?

[Mark Callow]

On 21/06/2014 05:35, Trevor Linton wrote:

I'm not sure, it's unfortunately one of those problems i'm unsure if there's a complete solution to. The documentation is very complete in emscripten.h, i'm generally a fan of looking at things from users perspectives.  Most who are looking at documentation or have questions would first go to the documentation (at least that's my experience), generally someone pokes around at a header file as a last resort (at least thats just me).  In addition, jekyll and wiki's have the luxury of layout which allows you to add images, diagrams, links to other sources.  So, i'd say simple notes in the header that refer to the URL for the documentation and keep all the documentation in one place.

The solution to this problem is tools like Doxygen. Such tools allow you to write the documentation in the .h file in a way from which the tool can generate more user friendly documentation. I think it is a good idea to have the full documentation with the code because it is more likely to get updated when the code is updated. Tools like Doxygen enable this.

[Alon Zakai]

We want to be able to write modern-looking docs that can be viewed online, as well as shipped together with an SDK in offline form (for a specific version). A third place we might want them is if we some day write a dedicated emscripten website, then the docs should be easily transferable to another online site. Github pages seems limited for the second and third use cases here, AFAICT.

- Alon

--

[Trevor Linton]

I should add, having somewhere that has all of the -s compiling flags would be helpful, I had to dig into the actual emcc python script to get an understanding of some of them.

To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-discuss+unsub...@googlegroups.com.

[Warren Seine]

Regarding the documentation content, here's what I would suggest:

• refactor the Technical Documentation into a User Guide
  
• remove any specific page from the main page (like "EGL support in Emscripten" or "Running html files with emrun")
• turn each subpage into an action (like "Compiling", "Binding", "Embedding", "Running", "Debugging", "Packaging", "Publishing")
• in a "Publishing", explain how to properly embed an Emscripten application (right now, I'm sure everybody copy/paste the generated HTML and hack it)
  
• make first time access easier
• make sure the Tutorial is the first thing people go through (I think it's good and should be highlighted even more)
• make a gist to build from source (I've made one but it's somehow broken) instead of listing steps for Linux (and remove any old confusing third-party links)
• move all screencasts, blog posts (official and unofficial), tutorials and slides out of the User Guide
• move any "Issues" subsection into one Troubleshooting page with complete error messages (so it can be indexed and searched)
• detail the project status
• turn the roadmap into a Trello board
• introduce the core team in a single place (with Twitter and GitHub handles, blogs)
• clean up the demo list
• separate demos from tools / engines / libraries (it's somehow confusing right now)
• update the demo list with direct link to the code (if available) and the actual demo
• format it as a table ("name", "description", "author", "submission date", "demo link", "source code")

I know it's a big list. What do you think?

[Alon Zakai]

Thanks for the detailed suggestions!

First and second main points sound great to me. We should add those to the docs plan.

I am not familiar with Trello, but will look into it. But I suspect anything very organized is more formal than this open source project can tolerate ;) I mean, it would likely get out of date quickly.

I suspect the demo list should stay on the current wiki, and not be part of the documentation revamp. Yes, we certainly need to keep it up to date and add links to code etc. as you suggest. Table format would be good also. If you or anyone else wants to do that, that would be great.

- Alon

--

You received this message because you are subscribed to the Google Groups "emscripten-discuss" group.

To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-disc...@googlegroups.com.

[Mark Callow]

"First thing, is this running after main() finished? See NO_EXIT_RUNTIME in src/settings.js regarding that."

One of the problems I would like the documentation revamp to solve is the need to provide references like the above. We want to be able to provide a URL that when clicked takes you straight to the relevant document (and even section) rather than being told to look at the source. See my earlier message about doxygen-like tools for a way to accomplish this and have the full documentation in the source, without duplication.

I think we should make a list of the problems to be solved before choosing technology.

Read on for some another comment ...

On 26/06/2014 03:20, Alon Zakai wrote:

I suspect the demo list should stay on the current wiki, and not be part of the documentation revamp. Yes, we certainly need to keep it up to date and add links to code etc. as you suggest. Table format would be good also. If you or anyone else wants to do that, that would be great.

+1. Making sure there is a link to the *working* demo is important.

[Alon Zakai]

Agreed, one of the goals should be to move docs out of source files like settings.js and emscripten.h.

- Alon

--

[Hamish Willee]

Hi All

I'm the technical writer who will be doing the "work". I have many years of general experience in writing for tools and programming languages, and also at working with communities to create documentation (you can find out a little about me here: http://www.linkedin.com/in/hamishwillee ). I'm used to working collaboratively, and I would REALLY appreciate your help to make this project successful. 

Thanks very much for all the suggestions and questions - I'll be reviewing them and including anything relevant in the plan. Below are some specific responses. If I've missed yours, then please repost or contact me directly on hamishwillee at gmail dot com.

Please re-split out appropriate sections if you believe they require further discussion. 

---------------

@msc

>What do you see as the advantages of Jekyll vs. a wiki? Over the Github Wiki? 

#HW 

The main goal of this project is to create a more professional documentation set, which will be used in both an improved website and in the SDK. The wiki is not suitable for this purpose.

The wiki is a great platform for community development, and we'll be mining the existing material as a base for the new documents. If people want to contribute specific topics to the documentation set then creating them on wiki first is a really good idea.

One reason I like jekyll is that it uses a near-compatible version of markdown syntax for the content (exactly the same as the wiki). Not only will this make porting the existing content trivial, but you will still be able to edit the content and preview it in almost exactly the same way as you do currently (of course the final output will look a little different as we'll be using different stylesheets).

Note also that the wiki will not be going away - though I will be removing duplicate material. 

> Will we have to learn YAML (yet another markup language)?

>It seems there may be something called YAML. I do not mean that language in particular.

#HW No (or only a trivial amount)

Jekyll parses markdown files which start with "front matter". This is almost exactly the same for each topic and is human readable. If editing an existing topic you would ignore this part of the file. If creating a new topic you will copy-paste from an existing topic and just update one or two files..

I will also be creating a "contributor" guide for whatever solution is selected.

---------------

@ Bruce Mitchener

> I really like working with Sphinx and ReStructured Text: http://sphinx-doc.org/

> I've used it (successfully) to produce thousands of pages of technical documentation, encompassing multiple books.  We publish these materials in HTML, PDF and ePub.  We've written our own extensions as needed and it has been pretty easy.

#HW

Thanks very much. I have not used Sphinx but I will review it and respond properly.

My uninformed 10 second view is that Markdown/wiki text is easier to learn and use than ReStructured text. There is also a real "ease of use" benefit of markdown on Github because it can be previewed by the author (on the site) without them having to learn the Jekyll toolchain. The ability to publish to PDF or ePub is great - but is not IMO a key selection criteria.

---------------

@ Warren Seine

> If you like Sphinx, you should definitely have a look at ReadTheDocs. Basically, it's a platform for hosting documentation from Sphinx source files. The source of the documentation stays on GitHub and documentation is regenerated on commit hooks. It's quite popular in the Python community, though there's nothing specific to the language.

#HW Thanks, I will check this out too.

---------------

@Trevor Linton

> I'd be happy to help. One aspect I think could use a very thorough once over is the emscripten.h C documentation, shouldn't be difficult bringing it to a wiki or jekyll.  Also, the emcc/em++ command line options, there are some options aren't documented (other than the paragraph found in the help). 

#HW This is very much in line with my thinking - as documenting this sort of thing is one way to work out the omissions in the higher level guide material. I also hope to create/source more complete documentation on the test code - and as part of that either separate out or better identify the code which works well as "example code"

In terms of the documentation in header files and tools, my experience is that it is best that documentation remains "in source" and is extracted using tools. 

> If there's anything you'd like me to take a pass at, let me know.

#HW Thank you. I certainly will! 

I don't yet know the established "ways of working" but I assume if you see a defect in docs you can create an issue and either assign or request that it be assigned to me. If you already know of specific omissions and are happy to contribute a proposed solution/text then please do. It does not have to be "perfect" as I will subedit.

---------------

@Alon

> I guess the first question here is where to put the docs - we have emscripten.h docs inline, and I'm worried about copying it to another place without removing the original, to avoid duplication and one being out of date etc. So the question is, is comments in the source better than a separate doc? Comes down to what people prefer I guess. Thoughts?

#HW My experience is that developers like documentation everywhere, but that as an author it makes sense to only have one master copy. The usual solution is to have in-source and extract using tools. Doxygen is a common solution to this problem, but depends on the format of the comments. 

---------------

@Trevor Linton

> I'm not sure, it's unfortunately one of those problems i'm unsure if there's a complete solution to. The documentation is very complete in emscripten.h, i'm generally a fan of looking at things from users perspectives.  Most who are looking at documentation or have questions would first go to the documentation (at least that's my experience), generally someone pokes around at a header file as a last resort (at least thats just me).  In addition, jekyll and wiki's have the luxury of layout which allows you to add images, diagrams, links to other sources.  So, i'd say simple notes in the header that refer to the URL for the documentation and keep all the documentation in one place.

#HW See previous comment. 

My concern about links is that URLs change. I like comments in source, because it encourages developers to update the documentation when the code changes.

---------------

@msc  

>>On 21/06/2014 05:35, Trevor Linton wrote:

>>I'm not sure, it's unfortunately one of those problems i'm unsure if there's a complete solution to. The documentation is very complete in emscripten.h, i'm generally a fan of looking at things from users perspectives.  Most who are looking at documentation or have questions would first go to the documentation (at least that's my experience), generally someone pokes around at a header file as a last resort (at least thats just me).  In addition, jekyll and wiki's have the luxury of layout which allows you to add images, diagrams, links to other sources.  So, i'd say simple notes in the header that refer to the URL for the documentation and keep all the documentation in one place.

>The solution to this problem is tools like Doxygen. Such tools allow you to write the documentation in the .h file in a way from which the tool can generate more user friendly documentation. I think it is a good idea to have the full documentation with the code because it is more likely to get updated when the code is updated. Tools like Doxygen enable this.

Regards

#HW Yes. To be very pedantic "the full documentation of the code in the code". There will be documentation that is not in the code. Doxygen is a good tool, but does require specific syntax for comments. 

#HW Note also, that we will want to make sure that the command line tool documentation also remains in-sync without our docs.

---------------

@Alon Zakai

> We want to be able to write modern-looking docs that can be viewed online, as well as shipped together with an SDK in offline form (for a specific version). A third place we might want them is if we some day write a dedicated emscripten website, then the docs should be easily transferable to another online site. Github pages seems limited for the second and third use cases here, AFAICT.

#HW The output of Jekyll is a static site which can be hosted anywhere. The limitation is that as it is static you can't run server side code (for example a database for logins or whatever). It is perfectly suitable for both the current proposed site on Github pages and the SDK (where you can't run server-side scripts anyway). 

Whether it is suitable for the "third case" depends the requirements of such a site. At that point if you needed the docs you could migrate them to the new system or just use Jekyll (or whatever) to to build them and then dump the raw HTML.

The minor limitation with Jekyll that I'll have to workaround is that we'll need separate entry points for the SDK and the site - so will need to export the SDK entry point somewhere during build.

---------------

@Trevor Linton

I should add, having somewhere that has all of the -s compiling flags would be helpful, I had to dig into the actual emcc python script to get an understanding of some of them.

#HW I will add this to "the list"

 

---------------

@Warren Seine

> Regarding the documentation content, here's what I would suggest:

refactor the Technical Documentation into a User Guide

remove any specific page from the main page (like "EGL support in Emscripten" or "Running html files with emrun")

turn each subpage into an action (like "Compiling", "Binding", "Embedding", "Running", "Debugging", "Packaging", "Publishing")

in a "Publishing", explain how to properly embed an Emscripten application (right now, I'm sure everybody copy/paste the generated HTML and hack it)

make first time access easier

make sure the Tutorial is the first thing people go through (I think it's good and should be highlighted even more)

move all screencasts, blog posts (official and unofficial), tutorials and slides out of the User Guide

move any "Issues" subsection into one Troubleshooting page with complete error messages (so it can be indexed and searched)

introduce the core team in a single place (with Twitter and GitHub handles, blogs)

clean up the demo list

separate demos from tools / engines / libraries (it's somehow confusing right now)

update the demo list with direct link to the code (if available) and the actual demo

format it as a table ("name", "description", "author", "submission date", "demo link", "source code")

I know it's a big list. What do you think?

#HW Yes :-) All of the above is very much in line with my current thinking and my understanding of best-practise. 

I will need some help for some of the clean-up. We should also identify those lists which really need to remain in wiki.

>make a gist to build from source (I've made one but it's somehow broken) instead of listing steps for Linux (and remove any old confusing third-party links)

#HW This is something I need to review to better understand. 

>detail the project status

#HW I'm thinking of a release notes section - or are you thinking of "roadmap"?

> turn the roadmap into a Trello board

Great minds :-) http://hamishwillee.github.io/2014/06/20/Trello-project-management-tools-and-burndown-charts/

I had already started one "for myself" - from which I was planning delivering a snapshot :-) If people want to email me their email details  (hamishwillee at gmail dot com) I'm happy to share it. 

---------------

@msc

>"First thing, is this running after main() finished? See NO_EXIT_RUNTIME in src/settings.js regarding that."

One of the problems I would like the documentation revamp to solve is the need to provide references like the above. We want to be able to provide a URL that when clicked takes you straight to the relevant document (and even section) rather than being told to look at the source. See my earlier message about doxygen-like tools for a way to accomplish this and have the full documentation in the source, without duplication.

I think we should make a list of the problems to be solved before choosing technology.

#HW Agreed.

> I suspect the demo list should stay on the current wiki, and not be part of the documentation revamp. Yes, we certainly need to keep it up to date and add links to code etc. as you suggest. Table format would be good also. If you or anyone else wants to do that, that would be great.

#HW I will need to review this because I don't know enough yet to evaluate. Generally speaking it that  makes sense to have "official" demos and examples in the documentation set, or at least linked from it. By official I mean "known to be impressive, and to work with current versions of the tool". Maintaining a less official list on wiki is a good idea.

#HW I can make the list a table, but will hold off until discussion complete.

[Hamish Willee]

Hi Bruce

In my last message I wrote: "I have not used Sphinx but I will review it and respond properly. My uninformed 10 second view is that Markdown/wiki text is easier to learn and use than ReStructured text. There is also a real "ease of use" benefit of markdown on Github because it can be previewed by the author (on the site) without them having to learn the Jekyll toolchain. The ability to publish to PDF or ePub is great - but is not IMO a key selection criteria."

A few hours later ....

Yes, Sphinx would also be a capable tool for the job. It is a more mature product, with more output formats, inbuilt support for internationalisation, good source cross referencing, and some excellent extensions. It "understands" that you're trying to create a document hierarchy and automatically supports all the indexing and output HTML to support that. It has plenty of good documentation, an active community, and good support. It wasn't obvious to me exactly how the documentation of the C++ code would work, but clearly it would simplify things if we could use a single toolchain. 

Jekyll is a less "refined" product, but its documentation is just as good, and it has an active community and support network. Jekyll does not force any structure or look and feel out of the box, which means that starting from scratch would be much harder. However you don't have to start from scratch - there is an existing "good" project (e.g. jekyllrb.com sources) which answers the open questions. I think a Jekyll site will be easier for anyone to customise and understand than a Sphinx configuration. My feeling would be very different if the main requirement was to extract the comments from source code.

A reason to choose Jekyll would be that it uses Markdown rather than ReStructured text. When hosting on Github this means authors can preview during development and get a pretty good idea of what it will look like without having to install the doc toolchain. They also have only one markup language to learn across wiki. This would be an advantage if most of you are only editing occasionally.

My only concern with Sphinx is that I'm not sure how easy it will be to modify the themes as needed, while I've got enough experience with Jekyll to know I can get it to do what we need. If I hadn't any experience of either solution I would be leaning towards Sphinx. 

I'm more than happy to go with the "will of the community" as both solutions would be effective. 

Thoughts?

Regards

H

[Bruce Mitchener]

On Mon, Jun 30, 2014 at 12:41 PM, Hamish Willee <hamish...@gmail.com> wrote:

Hi Bruce

In my last message I wrote: "I have not used Sphinx but I will review it and respond properly. My uninformed 10 second view is that Markdown/wiki text is easier to learn and use than ReStructured text. There is also a real "ease of use" benefit of markdown on Github because it can be previewed by the author (on the site) without them having to learn the Jekyll toolchain. The ability to publish to PDF or ePub is great - but is not IMO a key selection criteria."

A few hours later ....

I'm really happy to hear that you took the time to look at Sphinx.

 

Yes, Sphinx would also be a capable tool for the job. It is a more mature product, with more output formats, inbuilt support for internationalisation, good source cross referencing, and some excellent extensions. It "understands" that you're trying to create a document hierarchy and automatically supports all the indexing and output HTML to support that. It has plenty of good documentation, an active community, and good support. It wasn't obvious to me exactly how the documentation of the C++ code would work, but clearly it would simplify things if we could use a single toolchain. 

Sphinx can handle the C++ API doc as well (probably better than Jeykll).

One thing that I didn't mention before and that really sells Sphinx for me for doing book-sized works is the presence of strong support for indexes, not just tables of contents.

 

Jekyll is a less "refined" product, but its documentation is just as good, and it has an active community and support network. Jekyll does not force any structure or look and feel out of the box, which means that starting from scratch would be much harder. However you don't have to start from scratch - there is an existing "good" project (e.g. jekyllrb.com sources) which answers the open questions. I think a Jekyll site will be easier for anyone to customise and understand than a Sphinx configuration. My feeling would be very different if the main requirement was to extract the comments from source code.

 I agree with most of this. I didn't find Sphinx that difficult to deal with.

 

A reason to choose Jekyll would be that it uses Markdown rather than ReStructured text. When hosting on Github this means authors can preview during development and get a pretty good idea of what it will look like without having to install the doc toolchain. They also have only one markup language to learn across wiki. This would be an advantage if most of you are only editing occasionally.

GitHub can preview ReStructured Text documents fine (depending on what extensions you use).  GitHub's wiki can also support ReStructured Text pages, not just GitHub-flavored Markdown. 

 

My only concern with Sphinx is that I'm not sure how easy it will be to modify the themes as needed, while I've got enough experience with Jekyll to know I can get it to do what we need. If I hadn't any experience of either solution I would be leaning towards Sphinx. 

Templating is pretty easy. It is just Jinja2 templates which are pretty common in Python land. I've done some in the past, mainly by borrowing techniques from existing templates (it ships with a number of them).

 - Bruce

[Hamish Willee]

Hi Warren, MSC

On Tuesday, 24 June 2014 21:03:23 UTC+10, Warren Seine wrote:

Regarding the documentation content, here's what I would suggest:

• clean up the demo list
• separate demos from tools / engines / libraries (it's somehow confusing right now)

At this point they are all demos, in the sense that they demonstrate C++ code that was  ported using emscripten. We could separate them, but what would you group them as (they would not be helpful top level headings). Some options:

a) Rename "Demos" to "Emscripten-ported C++ code" to make it clear that some of these are tools and frameworks. 

b) Just have good graphical demo examples here (e.g. the games section). Move the other examples to their own wiki page and link from the bottom of the demos section.

• update the demo list with direct link to the code (if available) and the actual demo
• format it as a table ("name", "description", "author", "submission date", "demo link", "source code")I

I have formatted the list in a table as suggested. I made the name into a link, so perhaps should remove the "demo link" heading? 

Is it worth having a "version" column for the Emscripten version?

At this point my tidying the table further is not a priority. If anyone wishes to take on this task or add the missing information, please be my guest.

Thanks

Hamish

[Warren Seine]

On Monday, June 30, 2014 2:04:57 PM UTC+2, Hamish Willee wrote:

Hi Warren, MSC

Hi Hamish, thanks for the update!

On Tuesday, 24 June 2014 21:03:23 UTC+10, Warren Seine wrote:

Regarding the documentation content, here's what I would suggest:

• clean up the demo list
• separate demos from tools / engines / libraries (it's somehow confusing right now)

At this point they are all demos, in the sense that they demonstrate C++ code that was ported using emscripten.

My idea here was to separate the "wow effect" initiatives from emscripten-compatible C++ libraries. The first one is mostly to see what can be done. The second one has to avoid starting from scratch when porting code to HTML5. On the list, I can see Cocos2D, Box2D.js, Minko (disclaimer: I work for Aerys, the company behind Minko), Esenthel, Oryol, lzma.js, sql.js, all projects in the Programming Languages part...

Also, several links are broken (TeX), not relevant (Text-to-Speak) or even spam (OpenJPEG).

 

We could separate them, but what would you group them as (they would not be helpful top level headings). Some options:

a) Rename "Demos" to "Emscripten-ported C++ code" to make it clear that some of these are tools and frameworks. 

Pretty much everything would be "Emscripten-ported code". But considering my point above, not everything is a demo. Some are toolkits (de facto a demo, but re-usable).

 

b) Just have good graphical demo examples here (e.g. the games section). Move the other examples to their own wiki page and link from the bottom of the demos section.

 

Yes, only keep up-to-date, amazing demos.

• update the demo list with direct link to the code (if available) and the actual demo
• format it as a table ("name", "description", "author", "submission date", "demo link", "source code")I

I have formatted the list in a table as suggested. I made the name into a link, so perhaps should remove the "demo link" heading? 

Yes. 

 

Is it worth having a "version" column for the Emscripten version?

Not IMHO. And it will be hard to collect.

 

At this point my tidying the table further is not a priority. If anyone wishes to take on this task or add the missing information, please be my guest.

Ok.

 

Thanks

Hamish

[Alon Zakai]

I am also pretty open to either Sphinx or Jekyll. It seems both have easy markup syntaxes, can export static sites, are popular, and basically support what we want.

I couldn't find mention of the ability to extract docs from C++ header files among the Sphinx feature list, or docs. Maybe I didn't look in the right place? That does sound like a useful feature, I'd be curious to hear more about how it works. If it works well that might be a  good reason to prefer Sphinx.

- Alon

[Hamish Willee]

Hi Alon, Bruce,  et al.

Sphinx does not provide support "out of the box" for extracting C++ comments, but it does allow you to create a "domain" for C++ that allows you to declare C++ entities and link to them (as shown on my test project here). 

However it is possible to use the tool Breathe (http://breathe.readthedocs.org/en/latest/index.html) to convert Doxygen generated XML into the format used by Sphinx and import these. I tested this HERE on emscriptem.h. I had to make a number of very minor changes to the header to get this to generate (mostly just addition of an extra asterisk on the comment blocks). Unfortunately I can't yet get the linking to work, so I am following up with the author of Breathe.

I'm still not loving restructured text, but I am leaning further into the Sphinx camp because while the toolchain is becoming more complicated, it is all "standard stuff"

Regards

H

[Hamish Willee]

Hi All

Ways of working together on docs ...

Over the coming weeks/months I'll port the documentation and write a lot more. You will discover defects, and you have already discovered omissions. You may also want to create your own docs to go into the site. To make it easier to work with each other:

1.  If you know of an omission or defect in the current topics, please post as an issue on github and mark for my attention. An omission could be undocumented functions in Emscripten.h, through to a whole document you think is needed.
   
2. If you want to write your own topics, then create them on the wiki and ask in this list for review. I will migrate to the site once we're a bit further along (providing there is broad agreement that it should be included).
   
3. Post any suggestions here, or email me at hamishwillee at gmail dot com. 
   

Any other suggestions on how best to work together welcomed.

Regards

H

[Alon Zakai]

Another thing that occurred to me is that we have inline docs in JavaScript as well, not just C++ (e.g., ccall in src/preamble.js). I suppose these tools might work on that as well? Could make things a little more complex though. Overall it might just be simpler to move the docs out of source files and into dedicated docs files.

I don't feel strongly either way between Sphinx and Jekyll, I guess. Overall I slightly prefer the simpler option (Jekyll) as the benefits of the more complex one are not huge. But if you and others here prefer Sphinx that would be fine too.

- Alon

[Hamish Willee]

Let's go with Sphinx! 

Following my investigation I agree with Bruce's recommendation that Sphinx is more capable and will make some tasks (like linking to code) a lot easier. I still don't like ReStructured Text but it isn't a compelling reason not to use the tool. I also don't think the (perceived) simplicity of Jekyll is enough of a benefit if it makes some tasks harder.

If there is a strong objection in the next couple of days we can reconsider, but otherwise I am assuming we will be moving forward with Sphinx.

On Wednesday, 2 July 2014 03:48:22 UTC+10, Alon Zakai wrote:

Another thing that occurred to me is that we have inline docs in JavaScript as well, not just C++ (e.g., ccall in src/preamble.js). I suppose these tools might work on that as well? Could make things a little more complex though. Overall it might just be simpler to move the docs out of source files and into dedicated docs files.

 Doxygen supports JavaScript, but Breathe does not - so there is no easy way to import JavaScript automatically into Sphinx. However if we're going to have source-code documentation in the library in either case, Sphinx does this much better. Basically it has features to "understand" code (C++, JavaScript) so that these are indexed, and are easy to link to with a consistent syntax. Jekyll doesn't really understand anything other than page variables defined in the front-matter, so support for code indexing and linking would need to be added (or done manually :-) )

[Mark Callow]

On 02/07/2014 02:48, Alon Zakai wrote:

Another thing that occurred to me is that we have inline docs in JavaScript as well, not just C++ (e.g., ccall in src/preamble.js). I suppose these tools might work on that as well? Could make things a little more complex though. Overall it might just be simpler to move the docs out of source files and into dedicated docs files.

Documentation separate from the code inevitably gets out of date very quickly. Having the documentation and code together is obviously no guarantee that the documentation will be updated along with the code but it improves the chances hugely.

I urge no separation of docs and code.

[Alon Zakai]

I am leaning to prefer Sphinx based on the discussion here too. Jukka, what are your current thoughts?

Regarding docs in the code, given that we have just 2 or 3 files with docs in them, and they span 2 languages, and would require 2 extra tools to support, I think it would be simpler for us to maintain the docs outside those files. I do agree with the point that docs outside the code can more easily get behind, but since it is literally so few files, I think we can (1) mark them clearly as being documented elsewhere, and (2) maintain vigilance on keeping them up to date.

- Alon

[Jukka Jylänki]

Sounds ok, let's go with Sphinx. I use doxygen XML files as input to MathGeoLib docs ( http://clb.demon.fi/MathGeoLib/nightly/ ), so I'm familiar with doxygen. I think we can try at first embedding the docs from our sources and see how it looks and what the process is, and if the extra tools to maintain it becomes a burden and it doesn't give us much in the docs output pages, we can see about dropping them?

[Alon Zakai]

I would prefer to just move them out of the code into separate documentation files. It's just 2 files, so having extra things in the process to generate docs feels like overkill for small benefit. At some point we will run into some bug in those tools, if we use them...

- Alon

[Hamish Willee]

It may be more than 2 files, if we extract information from test and example code (I have not yet looked at that possibility).

I am very happy not to have a dependency on Breathe, which is in any case limited to C++ only. However I would consider it reasonable and easy to use Doxygen to generate the doc XML (this is a very stable tool) and then create a simple independent Python parser to extract the documentation and spit out Restructured Text files in Sphinx Domain format for C++ and JavaScript. 

This is much simpler than what Breathe does and would be simple to write and maintain. If it did break for whatever reason, we'd be no worse off - we'd have the restructured text files from our last "run" as a starting point. 

I'd consider writing such a script to import the file contents in the first place, as it would take about the same time/effort as manually copy-pasting the files into the right format and likely be more robust.

Convincing argument?

You received this message because you are subscribed to a topic in the Google Groups "emscripten-discuss" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/emscripten-discuss/blW_cmBHd3s/unsubscribe.
To unsubscribe from this group and all its topics, send an email to emscripten-disc...@googlegroups.com.

[Alon Zakai]

Hmm, I don't think we need any for test or sample code. It does seem like just 2 files. Adding a new tool, however simple, just for those really feels wrong to me. In other words, the sentence "if it did break" troubles me, when the upside feels extremely small ;)

- Alon

[Hamish Willee]

Hi @WarrenSeine et al

>On Tuesday, 24 June 2014 21:03:23 UTC+10, Warren Seine wrote:

• detail the project status
• turn the roadmap into a Trello board

I'm using a trello board emscripten-doc-site to build up the plan and to mind my "todo" list. If anyone would like to join then please email me your trello membership details directly: hamishwillee at gmail dot com. Note that this is not the "business" version so I don't have observer only access; feel free to add comments and cards but don't delete anything or move anything to closed that I'm working on :-)

Note also that you don't need Trello to see what needs review/my list of changes, because I have a changelist on the site itself. You can also search for page header status information "under-construction", "candidate" etc, and - where I have open questions I've included the text "HamishW". If I need specific review I'll also ask here!

• introduce the core team in a single place (with Twitter and GitHub handles, blogs)

On further consideration this may be useful, but probably would be better as a wiki article which can easily be kept up to date. I am considering is "out of scope" unless there is strong support for it being part of the documentation.

Regards

H

[Warren Seine]

On Wednesday, July 9, 2014 1:24:52 AM UTC+2, Hamish Willee wrote: 

• introduce the core team in a single place (with Twitter and GitHub handles, blogs)

On further consideration this may be useful, but probably would be better as a wiki article which can easily be kept up to date. I am considering is "out of scope" unless there is strong support for it being part of the documentation.

A wiki article sounds fine. Even if I don't feel strongly about it, I think this would be a good thing to learn more about the people behind the tech. AUTHORS.txt is more a "legal" thing than a way to reach people.

[Hamish Willee]

 I agree. From a "community" point of view it is useful to have profiles of key players and an understanding of their history in that community. 

[Alon Zakai]

True, but things change pretty quickly, and it's hard to know what to write up that doesn't miss anything. I think one indication that people can use is to look at the owners of the core repos, because that is guaranteed to be up to date. Also recent commits. Documenting this further seems not worth it to me.

- Alon

--

You received this message because you are subscribed to the Google Groups "emscripten-discuss" group.

To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-disc...@googlegroups.com.

[Hamish Willee]

Hi All

emscripten.h documentation is ready for review: https://dl.dropboxusercontent.com/u/3067678/emscripten-site/docs/docs/api-reference/emscripten.h.html

This is a manually created document. It includes changes to the function prototypes currently in incoming branch to make the function signatures simpler. 

I'm not completely convinced about the docs for emscripten_get_preloaded_image_data and there will need to be additional links to documents about EXPORTED_FUNCTIONS and other guide material when it exists.

All feedback welcomed! For example, you might reasonably feel that the functions are the most important information in any section, and hence typedefs and defines should be defined after these.

Regards

H

[Hamish Willee]

Hi All

The public API for Emscripten is now documented, and ready for review - see it here.

Please review emscripten.h, preamble.js, html5.h and the "Advanced" APIs document. Note that the API currently reflects incoming branch, so html5.h uses typdef'd function pointer callbacks rather than having these in the registration function.

Feel free to email me directly with responses.

What I'm looking for:

- Descriptions that are unclear

- Typographic errors

- Structure that doesn't "make sense"

- Missing APIs - APIs that should be public but aren't documented, or internal APIs that might reasonably be mistaken as public and should appear in the "advanced/internal API document.

- Missing exceptions - unexpected fail cases

- APIs that really need an code fragment as part of their API reference description (please provide if you have one)

Another nice feature of this release is that the wiki snapshot now fixes links to the other wiki snapshot articles, and all wiki "inline code markup" which corresponds to a public API item is now linked to those API items. The makes the wiki snapshot very much more usable and searchable than the "real" wiki.

Your review thoughts appreciated.

Regards

Hamish

[Alon Zakai]

Nice work. I think we should start to merge this in, that is, make a pull request that imports this in place of the current docs. Then changes can be just normal pull requests on the repo. Also, the sooner we merge the better as the relevant files do get changed all the time.

Some notes:

1. The EMSCRIPTEN_KEEPALIVE section has an example. Should it say "For example" or such before it, perhaps?

2. "Emits debugger" this should say "Emits <code>debugger;</code>", as that is a code fragment.

- Alon

[Hamish Willee]

Thanks for the feedback - I've fixed the two cases. 

>I think we should start to merge this in, that is, make a pull request that imports this in place of the current docs. Then changes can be just normal pull requests on the repo. Also, the sooner we merge the better as the relevant files do get changed all the time.

Sounds good. I think the pre-condition should be that we are also publishing the snapshot of the documents on github pages (and map to emscripten.org). 

My thought is that I'd spend some time on the home page entry point this week to get it to a minimal standard - still pointing to the wiki for most documents.

FYI Currently I'm building this on an Emscripten fork on my repo here, with the api reference docs here.

--
You received this message because you are subscribed to a topic in the Google Groups "emscripten-discuss" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/emscripten-discuss/blW_cmBHd3s/unsubscribe.
To unsubscribe from this group and all its topics, send an email to emscripten-disc...@googlegroups.com.

[Alon Zakai]

Sounds reasonable.

Question: Why are there

	mapped_wiki_inline_code['Pointer_stringify()']=':js:func:`Pointer_stringify`'

's in a python file there?

- Alon

[Hamish Willee]

>Question: Why are there

	mapped_wiki_inline_code['Pointer_stringify()']=':js:func:`Pointer_stringify`'

The wiki snapshot import code automatically imports from the wiki, and fixes up any text marked as inline code (e.g. `a code item`) to link to the proper API reference. This both makes the snapshot better, but also makes my port of the documents much easier when I start from wiki.

To do this mapping, I run  get_api_items_py across the api-reference documents to create the py file you are talking about (api_items.py). The api_items.py is then imported into main wiki importer script (get_wiki.py).

The get_api_items_py script would only need to be run occasionally and you could argue not needed at all once we have all the main reference in place. My thought was to put all of the scripts in a "build_scripts" folder and fully automate this. It is on the "big list". If you would like a different approach/architecture then more than happy to do that too.

Cheers

H