This is the final report for Google Season of Docs 2020 project CircuitVerse Interactive Book Consolidation and Improvements
CircuitVerse is an open source project aiming to provide a platform where circuits can be designed and simulated using a web-based graphical user interface. The logic simulator can be used to design up to complete CPU implementations, although it is designed primarily for educational use. Besides the technical documentation for the software, an online interactive book guides the user in learning digital logic design. The book allows the user to try out circuits directly from within the book for an interactive experience.
The book is in an early state of development and is currently lacking some relevant sections, the general structure is loose in terms of a flow connecting the different sections, and requires more detailed content. Moreover, according to the organisation, there are not guidelines to help contributors to collaborate to the project nor is a plan or road-map to guide contributions on which contents are needed and with which priority.
The aims of this proposal are to collaborate with the mentors to create contribution guidelines, produce a topic development plan and contribute with improving current content as well as create new content according to the development plan.
Copy of the original full proposal
The interactive book has the potential to be useful for a broad audience ranging from amateur electronic hobbyist and secondary education students to tertiary education students and professionals in need of refreshing or strengthening their skills in digital logic circuits.
In order to address the heterogeneity in the book’s users a “multi-layer” structure is proposed, where each layer correspond to increasing level of complexity and theoretical depth of the contents.
Therefore, the documentation’s structure grows in two dimensions, the first dimension corresponds to the logical or traditional sequence of topics in digital logic systems, while the second dimension represents the level.
For simplicity, only three layers of complexity are defined for each topic, corresponding to basic, medium and advanced levels.
All the proposed goals have been completed.
The following activities were agreed with the mentors. All of the activities have been carried out.
The content development plan had the following steps:
Currently, the CircuitVerse Interactive Book new version is in beta stage. It is temporarily available in the following GitHub repositories:
It includes the new structure as well as the re-organised previous content and new content. The new content embeds new interactive circuits designed with the CircuitVerse simulator.
The previous content still needs more clean-up, addition of proper references and links to the newer content when appropriate.
The first version of the contribution guidelines has been released. It has been based on similar documents from other open source projects, such as Wikibooks, the Linux Documentation Project and OpenStreetMap. It is expected that this document will evolve together with the community development around the book project. Also, a license and licensing procedure was proposed and is part of the contribution guidelines, since the previous contributions were not under any licensing scheme.
The following pull request are associated to the contributions to the documentation repository in GitHub:
The following list represents the new book’s structure (sections corresponding to the medium level are in bold, while advanced level sections are in bold and italics):
This section include some screenshots from new book sections showcasing the available features and some of the style guidelines.
The Boolean functions section screenshot shows the
jekyll-scholar plugins providing support for equations and bibliographies,
The following screenshot from the Binary cubes representation section
show figures rendered using a dedicated template which provides captioned
figures (not available with pure
Besides the above mentioned features, one of the new interactive circuits can be seen in the next screenshot taken from MUX-based functions section.
Another new feature provided by the
jekyll-spaceship plugin is the possibility
to create more complex tables, including equations, multi-row and multi-column
cell spans, CSS override and more.
The tables in the section Map-entered variables depicted in the next screenshot
make use of some of these capabilities.
Also, these tables use the workaround for captioning described in the guidelines.
Originally, it was expected that most of the project would be reviewing and re-arranging the previous content and creating the new sections. However, it was found at the beginning that the current Static Site Generator (SSG) used to deploy the book needed updating and improvements. Therefore, the newer upstream SSG version was installed from scratch, the book structure was implemented and the previous content was migrated. Nevertheless, the old SSG version had many custom made patches which were incompatible with the new version, so some updates in style and functionality have been created as issues and should be fixed soon in order to release the new version of the book.
Another challenge was that although the current SSG setup might be very well suited for general purpose documentation, book-like documentation is not well supported. To compensate the lack of features some plugins were added. To this end, it is recommended to evaluate in the near future whether the current infrastructure is the correct tool for maintaining a book-like documentation or it is better to migrate to another system with better support for the required tasks.
Although I have been an advocate of Free and Open Source projects for more than two decades and have submitted a few single, “one-shot” contributions to a handful of projects, this is the first time for me to deeply interact with a thriving community in a young project with high potential. It has been a wonderful experience.
Yet, it is tempting to detour from the main goals set for the project, since there are so many interesting issues with which to collaborate. It is important to remain focused and follow the projected plan in order to reach the desired outcome in the given time.
Besides the proposed goals and activities regarding the reorganisation and creation of the book’s contents, the following contributions were also made:
The following is a proposed list of possible future improvements: