[RFC]: Make code blocks on website documentation interactive

[ShivamAhir]

Full name

Shivam

University status

Yes

University name

National Institute Of Technology Kurukshetra

University program

Bachelors in Information Technology

Expected graduation

July 2024

Short biography

My name is Shivam, and I am from Faridabad, Haryana. Currently, I'm in my final year pursuing a Bachelor's in Information Technology from the National Institute of Technology Kurukshetra. Throughout my academic journey, I've gained a strong grasp of various programming languages and concepts, including C, C++, object-oriented programming, JavaScript, automata, compiler design, and web development technologies.

I hold a certificate of excellence in data structures and algorithms using C++, showcasing my proficiency in this area. My skill set extends to both frontend and backend development. On the frontend, I'm adept with HTML, CSS, JavaScript, ReactJS, and React Native, while on the backend, I'm experienced with Node.js, Express.js, and database management.

In terms of practical experience, I completed a six-month analyst internship at HSBC bank {Certificate}, where I primarily focused on frontend development using HTML, CSS, JavaScript, and React. Additionally, I gained valuable teaching experience during a four-month internship at Coding Ninjas as a teaching assistant, specializing in C++ {Certificate}. Furthermore, I've contributed as a freelance developer, primarily focusing on frontend development projects {Figma design}.

Timezone

GMT+5:30

Contact details

Email: 11shivam00@gmail.com , X: Shivam36098599 Linkedin: shivamahir

Platform

Mac

Editor

I prefer Visual Studio Code (VSCode) for its extensive community support, frequent updates, and versatility in handling various programming languages and frameworks. Its seamless integration with modern technologies like Git and Docker enhances the development workflow, making it my editor of choice.

Programming experience

Since my first year of college, I've actively engaged in programming, honing my skills in data structures and algorithms through platforms like LeetCode, GeeksforGeeks, Coding Ninjas, and InterviewBit. And i have successfully completed a Data Structures and Algorithms using C++ here is Certificate of Excellence.

Alongside, I've developed various projects using HTML, CSS, and JavaScript, ranging from simple applications like

• Color changer : I developed a basic project called "Color Changer" using HTML and CSS. This project features a button that, upon clicking, randomly changes the color of the screen.

• Calculator : The Calculator project I created utilizes HTML, CSS, and JavaScript to perform fundamental calculations such as addition and subtraction.

• Tic-Tac-Toe: This project is build using html, css and javascript where 2 user can play tic-tac-toe game

• Music player: I created demonstrates essential functionalities such as play, pause, next, and previous buttons for playing music videos. Additionally, users can navigate through the video by clicking on the timeline to move to a specific time. This project is built using HTML, CSS, and JavaScript.

• College website.: I designed a responsive college website as my second-semester final project, incorporating HTML, CSS, and JavaScript. The website serves as a platform to showcase essential information about my college, including its mission, programs offered, faculty, and campus facilities.

As my confidence grew, I ventured into learning modern technologies such as ReactJS, React Native, MaterialUI, Node.js, Express.js, along with database management systems like MySQL and MongoDB. This knowledge has been instrumental in crafting a variety of projects like:,

• Todo app: The Todo App project I developed utilizes React Native, enabling users to perform essential operations such as adding and deleting todos directly from their mobile devices.

• Full-stack project resembling an Apple product clone, complete with frontend and backend components. The frontend utilizes ReactJS, while the backend is powered by ExpressJS and MongoDB. Users can register, log in, and log out securely. They can view products along with their details, add products to their cart, and provide ratings for products. Additionally, users can access comments left by other users regarding the products.

• Weather app: This project developed using React Native enables users to check their current weather conditions and upcoming forecasts based on their location. This app utilizes the OpenWeather API to retrieve accurate weather information.

• Emporium: Emporium is a project I've been developing to enhance my frontend development skills, particularly focusing on learning MaterialUI. Currently, the project is non-responsive, but it serves as a platform for me to explore and implement various MaterialUI components and design principles.

Internship and freelance:

During my six-month internship at HSBC bank, I had the privilege of engaging in diverse projects, including:

• Built an interface for admin maker and checker in the UI-DDS project using React.js, and conducted functional testing on the project. Generated detailed test reports.
• Enhanced the interface for comparing manual and API test data, aimed at improving testing processes and facilitating decision-making for the team. Utilized HTML, CSS, and JavaScript.
• Developed test cases and performed parameter validation testing for CRA code. Generated comprehensive test reports.
• Certificate of internship

Additionally, I served as a Teaching Assistant, where my responsibilities included addressing students' queries pertaining to DSA and assisting them in problem-solving here is Certificate of internship

In a freelancing capacity, I've taken on the responsibility of developing entire frontends for mobile app projects here is figma design, further deepening my expertise and practical application of these technologies.

JavaScript experience

I have extensive experience with JavaScript, having utilized it in various projects ranging from frontend development to backend scripting. One of my favorite features of JavaScript is its versatility and flexibility, allowing me to work seamlessly across different platforms and environments. Its asynchronous nature through features like Promises and async/await has been particularly useful in handling asynchronous operations efficiently. Additionally, its extensive library support, including frameworks like ReactJS, React Native, and Node.js, further enhances its utility and enables me to build robust applications for diverse use cases.

However, if I were to highlight a least favorite feature, it would be JavaScript's weak typing system, which can sometimes lead to unexpected behavior or bugs, especially in large-scale projects. While TypeScript offers a solution to this issue by adding static typing, pure JavaScript lacks strong type checking, making it susceptible to certain types of errors. Despite this drawback, JavaScript's overall utility and widespread adoption make it an indispensable tool for modern web development.

Node.js experience

I've gained experience with Node.js and its libraries by completing courses on FreeCodeCamp. During these courses, I learned how to use Node.js along with Express.js to build backend services. I've also undertaken practical projects where I implemented various features such as sending data to the frontend, managing user feedback, and enabling users to interact with products by adding them to their cart.

C/Fortran experience

My experience primarily lies in C programming, which I started during my first semester. I've gained proficiency in fundamental concepts such as data types, control structures, functions, pointers, and memory management. Throughout my academic journey and practical projects, I've extensively applied C to solve various programming problems and implement algorithms and data structures.

As for Fortran, I don't have any specific knowledge or experience with it. My focus has been predominantly on C programming, which has served as my initial programming language and continues to be a core part of my programming skill set.

Interest in stdlib

I stumbled upon stdlib while browsing through Google's organization list, and I was immediately drawn to it because it utilizes technologies like C, C++, JavaScript, and Node.js – all of which align with my interests and skill set. Moreover, stdlib offers a wide array of project categories for GSOC 2024, which further piqued my interest.

My passion lies at the intersection of technology and open access to knowledge and information, and I believe stdlib is at the forefront of this movement. It has made remarkable strides in promoting open access and sharing of information, which resonates deeply with me. As an aspiring software engineer, I am thrilled at the prospect of collaborating with stdlib to develop technology that upholds these values and contributes to creating a more open and accessible world.

One aspect that particularly impresses me about stdlib is its commitment to diversity, equity, and inclusion. I am eager to work alongside individuals who prioritize these values, as it reflects the kind of inclusive and supportive environment I strive to be a part of.

Overall, I see working with stdlib as an incredible opportunity to not only enhance my technical skills but also to contribute meaningfully to a mission that aligns closely with my personal values. I look forward to the chance to help empower new users to efficiently utilize the built-in functionality and to be a part of a team dedicated to making a positive impact in the world.

Version control

Yes

Contributions to stdlib

I have submitted several pull requests aimed at migrating from C++ add-on interfaces to C add-on interfaces, as well as implementing various style and simplification changes to align with current project conventions. Additionally, I have enhanced some README files by including examples to provide better clarity and understanding for users.

Pull requested for Refactoring { successfully merge some high priority PR }

1. refactor: blas/ext/base/sapxsumkbn2 to follow current project conventions #1966 PR link
2. refactor: update blas/ext/base/dsumors to follow current project conventions #1968 PR link
3. refactor: update blas/ext/base/sasumpw to follow current project conventions #1969 PR link
4. update blas/ext/base/dapxsumors to follow current project conventions PR link
5. update blas/ext/base/dapxsumpw to follow current project conventions PR link
6. update blas/ext/base/dsapxsumpw to follow current project conventions PR link

Pull requested for improving readme { still open }

1. docs: improve README examples of stats/base/dists/invgamma namespace PR link
2. docs: improve README examples of stats/base/dists/gamma namespace PR link
3. docs: improve README examples of stats/base/dists/chi namespace PR link
4. docs: improve README examples of stats/base/dists/geometric namespace PR link
5. docs: improve README examples of stats/base/dists/triangular namespace PR link
6. docs: improve README examples of math/iter/sequences namespace PR link

Goals

Project Abstract:

The aim of this project is to enhance the user experience of our website documentation by implementing interactive code blocks. Currently, our documentation features static code examples which limit user engagement and understanding. By introducing interactive code shells using CodeMirror, users will be able to edit and manipulate code expressions, facilitating a deeper comprehension of the functions demonstrated. This initiative also involves developing APIs to provide real-time feedback to the code editor, dynamically loading relevant standard library packages, and implementing security measures to prevent malicious usage. Additionally, we will convert READMEs into structured data formats like JSON or XML, enabling easier transformation and integration into the interactive documentation interface. This is a idea in my mind for the code block Here is before and after look for isEven

Before

After

Prototype

I have build a small prototype for isEvent module

Prototype video

https://github.com/stdlib-js/google-summer-of-code/assets/74092725/71751bb0-6316-47b5-adc3-568d8ef1fca3

here is it's frontend code

here is its backend code

Prototype description I have try to develop a small prototype of code block for a small module isEven which basically tell weather a given integer is even or not even in the boolean form and it contain two block one is input and other is output for now I have taken simple textarea for demonstration only during my contribution in stdlib I will implement a dedicated code editor for the frontend and at the backend I import the isEven module and run with the user javascript code with the help of a api and show the result at the frontend

Detailed Description:

Our current documentation at https://stdlib.io/docs/api/latest lacks interactivity, hindering users' ability to experiment and learn effectively. To address this, we propose implementing interactive code blocks that allow users to modify expressions and observe real-time results. This will be achieved by integrating CodeMirror, a versatile code editor, into our documentation pages. Users will have the ability to edit code expressions within the documentation interface, facilitating a hands-on learning experience.

To support this functionality, we will convert README files into structured data formats such as JSON or XML. This conversion will streamline the transformation process and ensure seamless integration into the interactive documentation interface. Furthermore, we will develop APIs to provide real-time feedback to the code editor, enabling users to observe the effects of their modifications instantly.

Dynamic loading of relevant standard library packages is essential for providing comprehensive examples within the interactive code blocks. By lazily integrating standard library packages, we ensure that only necessary resources are loaded, optimizing performance and user experience.

Security is a paramount concern in enabling user interaction with code blocks. We will implement robust security measures to prevent malicious usage, safeguarding our platform and users' data integrity. This includes input validation, sanitization techniques, and possibly sandboxing code execution to mitigate potential risks.

Expected Outcomes:

1. Improved User Experience: The introduction of interactive code blocks will enhance user engagement and comprehension of our documentation.

2. Real-Time Feedback: Users will receive instant feedback on code modifications, allowing for iterative learning and experimentation.

3. Dynamic Loading: Relevant standard library packages will be dynamically loaded, optimizing performance and resource utilization.

4. Security Measures: Robust security protocols will be implemented to protect against malicious usage, ensuring the safety and integrity of our platform.

5. Ease of Transformation: Conversion of READMEs into structured data formats will streamline content management and integration processes, enabling efficient updates to the interactive documentation interface.

By implementing these enhancements, we anticipate a significant improvement in the usability and effectiveness of our website documentation, providing users with a more immersive and informative learning experience.

For executing the code, we can set up a dedicated Node.js server. The client will send the code to the server for execution and listen to a server-side event for the progress of execution. When the execution is complete, the client will request the server for the output using a unique execution ID provided with the server-side event. The server will store the output of each request against its execution ID in memory or in a database.

As the execution server is dedicated to executing stdlib-related code, it can have stdlib globally installed in the environment. However, there are limitations:

1. When users use other modules, they have to write import statements for them.

2. Users cannot use third-party dependencies other than stdlib. However, this also provides the benefit that users stick to trying and exploring stdlib code, which is the purpose of the editor.

3. Creating executable code blocks other than the example is a significant challenge, as a single transformer script is insufficient due to the diverse requirements of different blocks. In such cases, we can explore language models like ChatGPT to address the specific needs and complexities.

Regarding the click button, most people interact with the editor in this way as they find it more intuitive. However, we can experiment with showing output in comments as well.

Why this project?

This project aligns perfectly with my experience and technical stack, which includes HTML, CSS, JavaScript, React, and JSX. As a frontend developer, I consistently prioritize enhancing user experiences. This project aims to significantly improve user interaction with documentation by making all code blocks interactive. Users will have the ability to code their own programs directly within the documentation, thereby gaining a deeper understanding of the concepts.

I have prior experience using similar interactive code editors on online tutorial platforms like GeeksforGeeks. These editors facilitate a seamless learning experience, allowing users to experiment with code in real-time. I believe implementing such functionality in documentation can greatly benefit users in comprehending complex concepts more effectively.

Participating in this project presents an exciting opportunity for me to make a meaningful impact on others' learning processes. Contributing to the development of a tool that empowers users to learn and understand programming concepts more efficiently brings me immense satisfaction.

Moreover, I view this project as a significant opportunity for my career growth. Building a project with the potential to positively impact a large user base aligns perfectly with my professional aspirations. I am eager to collaborate on this project and contribute to its success, ultimately making a difference in the learning journey of many individuals.

Qualifications

As an Information Technology professional with a comprehensive skill set encompassing both frontend and backend development, I am well-equipped to undertake the challenges presented by this project. My proficiency extends across a range of technologies including HTML, CSS, JavaScript, React.js, React Native, MaterialUI, Node.js, Express, and various database systems.

With a blend of hands-on experience and formal education, I bring a solid foundation to the table. I have successfully completed numerous learning projects that have honed my abilities, and my tenure at HSBC provided valuable exposure to real-world development scenarios. Moreover, my freelance work as a React Native developer has allowed me to navigate diverse project requirements and deliverables, reinforcing my adaptability and problem-solving skills.

In terms of project delivery, I have a proven track record of meeting deadlines and exceeding expectations. I understand the importance of adhering to timelines while maintaining high-quality standards, a principle demonstrated through my previous project executions.

While my expertise primarily lies in frontend and backend development, I am committed to continuously expanding my knowledge base. I actively seek opportunities for professional development, whether through online courses, industry conferences, or relevant literature. This dedication ensures that I stay abreast of the latest advancements and best practices in the field, enabling me to provide innovative solutions tailored to the project's requirements.

Prior art

In my exploration of building a code editor for web platforms, I found CodeMirror, a versatile code editor component designed for the web. It provides a robust set of features for implementing a text input field with extensive editing capabilities. Additionally, CodeMirror offers a rich programming interface, enabling further customisation and extension to suit specific project requirements.

I found a blog titled Building A Web Code Editor which gives a step-by-step guide on how to create a code editor using CodeMirror.

I also found a YouTube tutorial that explains how to build a code editor for different programming languages like C++, JavaScript, and Python. It also teaches how to create an API for the code editor.

Commitment

During the Google Summer of Code 2024 program, I am fully committed to dedicating approximately 20-22 effective hours per week to the project. This commitment is grounded in my prior experience of successfully managing up to 40 hours per week during my internship, showcasing my ability to effectively allocate and manage time.

Upon the conclusion of the program, I am eager to remain actively engaged with the organization. My goal is to provide ongoing support and guidance to new members, utilizing my experience to contribute to the organization's continued growth and success.

While I anticipate that my end-semester exams will occur at the end of May, I assure you that I will be fully available during my summer break starting from June.

Recognizing the significance of this project, I intend to prioritize it by dedicating full-time hours throughout the summer. In the event of any unforeseen disruptions, I am committed to maintaining proactive communication with my mentor. This ensures transparency and enables me to compensate for any lost time by investing additional hours in subsequent weeks to ensure the successful achievement of project milestones.

Schedule

Assuming a 12 week schedule,

• Community Bonding Period:

• During this phase, I will immerse myself in understanding the project thoroughly. I'll conduct independent research and engage in discussions with my mentor to gain deeper insights.

• Week 1:

• Prioritizing the conversion of README files into structured JSON or XML formats via an automated script. Upon completion, transitioning to the frontend implementation of interactive code blocks.

• Week 2:

• Focused on completing the implementation of responsive code blocks using CodeMirror, which will encompass a code editor area with additional functionality. This includes essential features such as the ability to run code, copy snippets, edit content, and toggle between light and dark mode for optimal viewing.

• Week 3 :

• Testing will be the primary focus during this phase. Upon successful testing, I will proceed to develop the API responsible for executing the code present in the editor.

• Week 4 to Week 5:

• The initiation of work on the subsequent phase of the API involves executing user code with dynamic loading of relevant standard library packages.

• Week 6: (midterm)

• By the midterm milestone, my goal is to have all planned features implemented and fully functional.

• Week 7:

• During this period, my focus will be on API and its integration testing and enhancement.

• Week 8:

• I will dedicate this week to enhancing user flexibility by facilitating easy switching between ES5 and ES6 for code blocks.

• Week 9:

• Manual testing for quality assurance will be conducted rigorously.
• Feedback from both the community and my mentor will be solicited and incorporated for further improvement.

• Week 10:

• I will focus on lazily integrating a code editor into documentation pages to optimise user experience by loading required components efficiently.

• Week 11:

• Implementing robust security measures to safeguard against malicious usage will be my priority during this week.

• Week 12:

• Testing and refinement will be the key activities during this phase, ensuring that the project meets all requirements and standards.

• Final Week:

• Submission of the project code and comprehensive documentation will mark the culmination of the project, ensuring a successful completion and delivery.

Notes:

• The community bonding period is a 3 week period built into GSoC to help you get to know the project community and participate in project discussion. This is an opportunity for you to setup your local development environment, learn how the project's source control works, refine your project plan, read any necessary documentation, and otherwise prepare to execute on your project project proposal.
• Usually, even week 1 deliverables include some code.
• By week 6, you need enough done at this point for your mentor to evaluate your progress and pass you. Usually, you want to be a bit more than halfway done.
• By week 11, you may want to "code freeze" and focus on completing any tests and/or documentation.
• During the final week, you'll be submitting your project.

Related issues

No response

Checklist

• [X] I have read and understood the Code of Conduct.
• [X] I have read and understood the application materials found in this repository.
• [X] I understand that plagiarism will not be tolerated, and I have authored this application in my own words.
• [X] I have read and understood the patch requirement which is necessary for my application to be considered for acceptance.
• [X] The issue name begins with [RFC]: and succinctly describes your proposal.
• [X] I understand that, in order to apply to be a GSoC contributor, I must submit my final application to https://summerofcode.withgoogle.com/ before the submission deadline.

[Pranavchiku]

Hello @ShivamAhir, creating json or xml files for readme will be difficult to scale for each package, maybe you can write a parser or a script that creates it from existing readme and use it. Also, it will be really helpful if you can thoroughly explain and provide a prototype for small package.

[ShivamAhir]

@Pranavchiku, appreciate the suggestion! Automating the process of creating structured files from existing readme content through a parser or script sounds like a practical solution for scalability. I'll focus on implementing this approach and will provide a detailed explanation along with a prototype for a small package. Thank you for your valuable input!

[ShivamAhir]

Hello @Pranavchiku I have added a basic prototype for isEven module

[kgryte]

@ShivamAhir Thank you for sharing your draft proposal. A few comments:

1. In your prototype, you perform an async request for an examples/index.js file. That works for that particular package, but will not work more generally. For example, other code blocks in a package's docs don't have corresponding JavaScript files present on the server, so those code blocks will need to be transformed and make executable. Additionally, you'll want to have some sort of way to solve the dependency problem. Namely, you need a way to lazily load, on demand, various example dependencies (e.g., local files, other packages, etc). As the code blocks will be editable, users will be able to potentially query for new packages which were not originally in the README code blocks. Hence, to make those things work, we'll need some way to dynamically load packages on demand. One possibility is to use the ESM module builds available in standalone repositories (see, e.g., https://github.com/stdlib-js/blas-ext-base-dnansumpw). In short, figuring out the build aspect of this project is critical to its success.
2. One idea we discussed internally when considering the original idea is the ability to utilize the doctest comments as a means for showing real-time return values, instead of relying on separate output textareas. And in general, it would be great if a user did not have to explicitly click "run" in order for examples to execute. I'd be interested in hearing your thoughts on how this could be done.

[steff456]

@ShivamAhir thanks for opening this draft proposal!

I just have one question for you,

1. Is this going to work for packages that have examples in C/C++ code?

[ShivamAhir]

@kgryte Thank you for the feedback.

For executing the code, we can set up a dedicated Node.js server. The client will send the code to the server for execution and listen to a server-side event for the progress of execution. When the execution is complete, the client will request the server for the output using a unique execution ID provided with the server-side event. The server will store the output of each request against its execution ID in memory or in a database.

As the execution server is dedicated to executing stdlib-related code, it can have stdlib globally installed in the environment. However, there are limitations:

1. When users use other modules, they have to write import statements for them.
2. Users cannot use third-party dependencies other than stdlib. However, this also provides the benefit that users stick to trying and exploring stdlib code, which is the purpose of the editor.
3. Creating executable code blocks other than the example is a significant challenge, as a single transformer script is insufficient due to the diverse requirements of different blocks. In such cases, we can explore language models like ChatGPT to address the specific needs and complexities.

Regarding the click button, most people interact with the editor in this way as they find it more intuitive. However, we can experiment with showing output in comments as well.

[ShivamAhir]

@steff456 The current approach does not support this. If we were to add support for C/C++ code as well, it would steer the project more towards a general online IDE, which might deviate slightly from the original use case. However, exploring that possibility is also an option.

[kgryte]

You can ignore running C/C++ examples. That should be considered beyond the scope of this project.