go-go-web VS Docusaurus

[metadata] name = gogoweb version = 1.0.3 author = Katie Liu author_email = [email protected] description = Command-line tool that converts .txt or .md files into .html files. long_description = file: README.md long_description_content_type = text/markdown url = https://github.com/kliu57/go-go-web project_urls = Bug Tracker = https://github.com/kliu57/go-go-web/issues classifiers = Programming Language :: Python :: 3 License :: OSI Approved :: MIT License Operating System :: OS Independent [options] package_dir = = src packages = find: python_requires = >=3.7 [options.packages.find] where = src

For this lab exercise I had the opportunity to add unit tests to a classmate's project and experience their CI workflow. For this exercise I worked on go-go-web by kliu57. Go-Go Web is written in Python and uses the pytest testing framework. This was my first time writing tests for pytest, but I found the pytest docs helpful. However, more helpful was the information provided in the associated issue and the tests already written, which helped me write the test I needed in the author's preferences.

This week, I am using Continuous Integration to automatically lint and test my open source project whenever the code is pulled or pushed to GitHub!

This week I want to add a new feature to my text to HTML converter, go-go-web. The feature I plan to add is Markdown Front Matter support. When a user converts an .md file to .html using my program, my program would be able to convert Front Matter in the .md file into metadata tag content in the resulting .html file.

I chose to write my program in Python while she used Java. Aside from syntax differences, she has much more exception handling in her code compared to mine. It made me think that I should add more exception handling to my own code. Having another person test my code definitely helps to find more issues. She discovered that I missed implementing the spec for deleting the default output folder at the start of the run. Also, she uses a VS Code extension called Pylint which helped to find many problems with my code. Pylint found many issues with my code which were not best practice, such as not specifying an encoding when reading from a file, or using an f-string that does not have any interpolated variables.

For this challenge, I've built a simple static website based on Docusaurus for tutorials and blog posts. As I'm not too seasoned with Frontend development, I only made small changes to the template, and added some very simple blog posts and tutorials there.

Dumi. A static site generator specifically designed for component library development. Look at it as something between Storybook and Docusaurus inside the Umi world (but much better integrated between each other, presumably).

Static site generators like Docusaurus offer flexibility for teams comfortable with Markdown and Git workflows

I really like the idea and what you’re building here. That said, I’d argue the documentation website is the face of any open-source project. Reinventing the wheel rarely ends well — the current docs are hard to navigate and read.

Just use an off-the-shelf solution for docs, like Docusaurus, for example:

https://github.com/facebook/docusaurus

Static websites are so good that they even have their own three-letter abbreviation: SSG (Static Site Generation). And of course, there are plenty of frameworks that generate them for you, no need in manual labour: Next.js supports SSG, Gatsby is still pretty popular, lots of people love Docusaurus, Astro promises the best performance, and probably many more.

hCaptcha docs is built using Docusaurus and their developer guide provides a vanilla example, but there’s framework specific examples provided as well.

Create visibility: A good mental model of your systems, data and code is beneficial to solving for errors so create tangible mind maps or documentation for the whole team to benefit from. Miro and Docusaurus are excellent tools for this.

VitePress and Docusaurus seem decent. I think VitePress might be more suited to blogging, but I admit I haven’t actually used or tested either.

https://docusaurus.io/

https://vitepress.dev/

For efficient workflows, Commander.js offers a custom CLI, while Docusaurus powers documentation, ensuring that everything is easy to find and well-maintained.

I am aware of Docusaurus, since I have seen other documentation and some of our course material site built on it. Under the hood it uses React so I was familiar with it. But this documentation website was written in Python. Although I'm not a fan of Python, it intrigued me, since not only it is written in python, more specifically using Sphinx which utilizes reStructuredText as its markup language. There was Makefile in it as well. A lot of new things but it looked very interesting.