Yaydoc consists of two components:
- A configuration for various Continuous Integration software including Travis CI among others.
- A Web User Interface
Since the initial stage of its development, the team has been focused on developing a `documentation generation` script and a `publish to Github Pages` script. These scripts have been developed and tested by using Travis CI.
We are now at that stage in the development of the project that we can generate the documentation of a project and keep it updated with every push in the Github repository that consists of changes in the documentation. A sample of this can be seen at https://yaydoc.fossasia.org which is a deployment of the documentation of Yaydoc using its own scripts.
After having enough confidence in the working of the script, we have now shifted our inclination towards developing a Web User Interface for the app. The WebUI is intended to perform various functionalities. These include, among others:
- Generate the documentation and Download the static files in a compressed format.
- Generate the documentation and make them available for a Preview
- Generate the documentation and Deploy them to Heroku
- Generate the documentation and Deploy them to web server using SFTP
NOTE:- The aforementioned functionalities are not exhaustive. Also, they are not certain to be developed if they are not fruitful for the users of Yaydoc. We do not intend to bloat the application with features and functionalities that may never be used.
The first issue that comes with developing any Web Application is the selection of its technology stack. With a huge number of languages and their web application frameworks, it becomes very difficult to reach a conclusion. After a lot of discussions, NodeJS was selected.
The User Interface involves various technologies including
- ExpressJS – A minimal and flexible Node.js web application framework.
- Pug (ex – Jade) – A high-performance template engine implemented for NodeJS.
ExpressJS is set up using the express-generator as it prepares a proper minimal architecture which makes it easy to scale up the application. Since the HTML part of the application will be minimal, Pug was chosen as it has a very clean and easy to read syntax. The use of Socket.IO became necessary as the app has a bidirectional communication with the `GENERATE` script sending its log output to the front-end.
Components of the Web User Interface
The UI consists of a Form that asks the user to input
- Email address – To provide a unique identity for a user to isolate the documentation
- GITURL – URL of the repository which consists the docs to be generated
- Doc Theme – A dropdown that consists of built in Sphinx themes.
Out of the various arguments used to generate documentation in Sphinx, following are assumed
- AUTHOR – Name of the user/organization of the repository
- PROJECTNAME – Name of the repository
- DOCPATH – Documentations are assumed to be stored at “docs/”
Apart from the form, the UI also has a block that is used to display the logs while the bash script is running in the backend.
The components defined above are those that have been developed and are being tested rigorously. Since the app is constantly being developed with new features added almost daily, new components will be added to the User Interface.