A sample format for exercises [GSoC]

[vishakha-lall]

@norvig @Nalinc, I have been working on developing a prototype format to display all the exercises of the book on Github Pages. I have used Angularjs as the client side framework to ensure a single page website. This would mean faster loading and better resource utilization. The template routing of angular components on Github pages, however, is not straightforward, which is why I have worked on using ng-build to modify the base-href. I have the sample page hosted here. I have used the markdown files of Introduction chapter to create a sample of the page, I still need to work on the figure links. I have used MathJax (following @Nalinc 's implementation) for the Latex equations and variables. This is the first prototype that I have created and requires a lot of design work and links. I have spent time realising the best framework to use and the routing method. Please review this and let me know if I am working in the correct direction. I have a lot of innovative things in mind to ensure that the exercises are interactive for the readers :)

[vishakha-lall]

I am also planning to work on creating additional functionality where students can rank these exercises based on difficulty level and relevance to the content. I would love to get reviews before I add some more code to implement that.

[Nalinc]

The sample page looks good @vishakha-lall. Here's my feedback. The repository behind your sample implementation indicates that these exercises are written in HTML instead of Markdown to host the pages on Github. This doesn't mean we will not use HTML at all. It would be interesting to use HTML/CSS for the overall 'theme', Javascript for 'interactivity' and Markdown to manage 'exercises'. The idea is to keep content (of exercises) separate from styling and interaction logic While we can do this with semantic HTML tags, using Markdown would be a more logical approach. Moreover, since Markdown files are easy to edit and preview on Github, it would speed up the development/review cycle and make aima-exercises more open to future contributors.

One way to address these concerns is to use Jekyll, but we should look at other static site generators befire we come to a decision. Have a look at the discussions in this thread

[vishakha-lall]

I was wondering the same, that adding HTML tags would be a manual process. Thank you for the suggestion, I will update that, so that we can move forward. Jekyll does sound like the obvious choice for Github pages, I will see if other static generators have advantages over Jekyll.

[anandwana001]

@vishakha-lall Could you update the progress so that we can work accordingly! @Nalinc I am thinking if we could first propose the sample design to mentors first and then after they confirm we can start developing it!

[Nalinc]

@anandwana001 Yes, it is better to work on a single chapter to test a design and get feedback (rather than porting a bunch of chapters). Remember, we need to keep a balance between exploration and exploitation. There is no point in exploiting a design before we have explored enough options. Also, if @vishakha-lall is working on using AngularJs for the frontend, you should probably look at other options :)

[vishakha-lall]

@Nalinc Yes, I am trying to work on a sample that integrates the single page client-side functionality of AngularJS with the markdown benefits of Jekyll. Let's hope that works well. Right now I am struggling with the fact that both use {{ }} and Jekyll considers that as liquid content.

[anandwana001]

@vishakha-lall any progress you want to share!

[vishakha-lall]

@norvig @Nalinc Can you give me some feedback on this Jekyll page I created. I have implemented the first 3 chapters of the book. They can be accessed from the collapsible navigation bar on the left, as well as the contents page. I have used MathJax to load the Latex math equations.

[norvig]

@vishakha-lall I like what you've done. Your design sense is nice and simple; I think you're on the right track.

[norvig]

I also agree with @Nalinc that it would be good to not write raw html, but to use markdown to create exercises, and then render them into the final displayed form.

[Nalinc]

This looks really good @vishakha-lall . However, I could not see any AngularJS in your sample. Didn't you mention that you will be exploring the use of AngularJs with Jekyll? Many people have already explored Jekyll as a potential option, and we need to explore other options as much as possible before we decide to stick with one. Though Jekyll definitely seems promising, we haven't decided on using Jekyll yet. Since aima-exercises is a new project, the challenge is to not to go deeper into one option but to ensure that we do not leave any stone unturned. Following table describes the possible options that have been explored(or suggested) by people so far (I hope I haven't missed anyone). I am updating it with your name.

Possible hosting option	Suggested by	Explored by	Demo
Markdown	@norvig	@Nalin, @ansh103, @Sayan98, @Dragneel7, @nvinayvarma189, @sambitdash	Demo
Jupyter Notebooks	@norvig, @Nalin	@Nalin, @KaustabhGanguly	Demo1, Demo2
HTML+MathJax	@norvig	@Nalin	Demo
Hosting on StackExchange	@norvig	None	NA
Kaggle	@norvig	@Dan and @Meghan	Demo
Wordpress	@heisenbuug	None	NA
Jekyll	@yakout	@yakout, @Nalin, @heisenbuug, @vishakha-lall	Demo 1, Demo 2, Demo 3, Demo 4
AngularJs	@vishakha-lall	@vishakha-lall	Demo
Firebase	@anandwana001	None	NA

It would be really helpful if someone can explore the breadth(instead of the depth) of available options, either new ones, or any of the suggested ones. It is totally fine to explore Jekyll in detail, but make sure you don't do anything which has already been done :) For instance, @heisenbuug suggested some really interesting ideas in his sample (like breadcrumb, sidebar toc, academic themes etc), but most of these have already been explored.

[anandwana001]

@Nalinc @norvig I had found this article which clearly specify that we can go for firebase if we want dynamic data on our GitHub page I just have a suggestion/thought you can help me with. As we all are focusing on a website for showing us exercises with other features like login, mentor access, student classroom etc. Can't we go for a mobile app, according to me if we go for a mobile app, we can be more personalized with students in terms of exercise, student classroom, chat with a mentor, and more features can be included in future?

[Nalinc]

@anandwana001 Firebase is nice, but there is a minor issue. You'd need to include firebase API key, authDomain and databaseURL in your code to integrate Firebase. In an opensource project like aima-exercises, it could be a security vulnerability if these credentials are openly accessible. That's the reason why this article made a private repository for demonstration. Mobile app is an interesting idea, but I believe it is not one of the top priorities for our community this year.

[anandwana001]

@Nalinc okay, Maybe community get interested in the mobile application, we can start as soon as possible. We can do native one or we can go for the trendy Flutter to make app hybrid. As nowadays everyone getting started with Flutter, if we have a product in this GSOC using flutter it will look good in the community.

[vishakha-lall]

@norvig Thank you for your feedback. I have worked on enhancing the prototype design using Angular JS.

• I have used Angular JS to send requests to the Github API.
• I am establishing an OAuth connection.
• I have made a new issue in my repository for a specific chapter (Chapter 1 for demonstration).
• I am retrieving all comments on that issue, specific to that chapter. This was students can ask and resolve queries on the Chapter Exercise page itself.

You can see this demonstration here. For demonstration purposes, I have only worked on comments for Chapter 1. You can scroll to the bottom to see the implementation. Try adding a new comment on the link and see it on the Github page(refresh, the issue comments sometimes take about 30s to be available in the API to be requested).

This method can be used to exploit the 'static' nature of Github pages and include dynamic content. This can be extended to other API's as well, without the need for any server-side code. With further enhancement, I can modify the design to allow the reader to add comments on the page itself.

@Nalinc Can you add this Angular JS demo to the table too? :)

[Nalinc]

@vishakha-lall I have updated the table. One thing I really like about your implementation is the way you managed comments. All previous demos I know of, use Disqus for comments(including my own implementation). Creating Github issues to comment is noval.

[nvinayvarma189]

Hey everyone, I've researched about hosting a community through firebase as suggested by @anandwana001. I'm very much impressed with it's hosting, real database, authentication, storage features and I thought that it would be apt for us. I tried implementing the ranking system here and hosted it using firebase.

I wanted to store these number of upvotes/downvotes in a database and tried including the authentication too. I have it my local machine but I haven't deployed it yet. Then when I dug in a bit deeper, I came across its security issue like @Nalinc mentioned and I don't think that we can oversee it.

Now I see @norvig interested in Kaggle and there is much to be explored, I guess. StackExchange also sounds great. I assume that for hosting a community kaggle and StackExchange are the options left. Should we go for kaggle or shall we see if there are any advantages in choosing StackExchange over kaggle?

Maybe @norvig had already considered the possibilities and ended up with kaggle (he knows the best about the project though). I request everyone to project their views. Also If anything is unclear about the ranking system I implemented or about my approach, please let me know.

[vishakha-lall]

Thank you @Nalinc , I did come across Disqus however it required a separate account to handle all comments which didn't seem like the best solution for an Open Source project. That was the motivation behind using the Github API :) I'm glad you liked it.

[Nalinc]

I assume that for hosting a community kaggle and StackExchange are the options left.

@nvinayvarma189 TBH, StackExchange is one of my favorite community too and I have been pretty active on it. The issue is, the process to host a StackExchange Community is tricky. There are two options to host a StackExchange community

• Get a StackOverflow Enterprise, or
• Go through the Area51 proposal process.

Option 1 is of course out of the question because we are not an 'enterprise'. As for Option 2, the process is pretty rigorous. First, to submit a proposal, one need to have a certain reputation within the community(we are covered on this front). Second, the proposals go through Area 51 which is essentially the staging area for new sites. Once they clear this phase, they are launched in beta and after that, they have to prove their worth in public beta before they become live. Though Option 2 doesn't cost money, it needs significant contributions from community members of the proposed site.

Entire process itself is community-driven and consider a number of factors (questions per day, answer ratio, number of visits, number of avid users etc). If any of these factors don't match, the proposal is rejected! Here's a proposal from Artificial Intelligence community to host a site on StackExchange. Despite being an active area, even they need to work on their answer %.

Another option is using Discourse for discussions on exercise-questions (and create labels based on chapters). Discourse has been a popular choice for other communities too (Twitter, Ubuntu, How-To-Geek etc). It has the same look and feel as StackExchange and is by the same person who created StackOverflow, Jeff Atwood. The issue here is, a fully-functional version of Discourse would involve setting up our own server and some components (like email support) would cost money (though we can even decide to not use such components at all).

@norvig We haven't really discussed Discourse here, have we?

[nvinayvarma189]

Yeah, thanks @Nalinc for pointing out the issues. For now, It is evident that StackExchange may not be suitable for us. If having separate pages for hosting the exercises and for having the discussions is advisable then Discourse looks great. Obviously, such platforms get commercial as time passes and we might not want that. I've also explored into such platforms like Muut (also costs money). phpBB works fine but the layout is too old and would not be comfortable to use.

[stabgan]

@nvinayvarma189 the firebase integrated content is good , but when reloading it is resetting . If that's the case , we can do it with html/css too . But it will reset when refreshed .

[nvinayvarma189]

@KaustabhGanguly It is actually an HTML/CSS file. Like I mentioned, this is just to show how the basic implementation will be. I have integrated it with a database, storing the number of upvotes/downvotes for a question and publishing them back to the console with all the details. I have it on my local machine and when I was about to deploy it, I came to know about the security issue which @Nalinc mentioned in this thread itself. So I did not deploy it then. Now I deployed it here. Try entering your name and submit it. later upvote/downvote a question. Look at the console to see the changes. There are many other things to be improved, but I did not develop it after I came across the security issue. Please let me know if anything is wrong.

[Nalinc]

@vishakha-lall @nvinayvarma189 @KaustabhGanguly, @anandwana001 I really appreciate your inputs on this thread, but now we are planning to pivot around Kaggle to see possibilities of using it to host aima-exercises. Closing this issue, but would love to get your feedback on https://github.com/aimacode/aima-exercises/issues/21