Port fortran-lang.org to Sphinx

Google Summer of Code, 2022

Author: Henil Shalin Panchal (henilp105)

fortran-lang/webpage

Project Details

Project Title: Port fortran-lang.org to Sphinx
Organization: Fortran-lang
Weekly Blog links: Fortran-lang Discourse
Mentors : Sebastian Ehlert
Rohit Goswami

Abstract

Fortran-lang.org is going through a complete overhaul, allowing us to work on a new, improved website with the latest tech stacks and enhanced performance. It has been a fantastic experience participating in Google Summer of Code 2022 with Fortran-lang. I am very grateful to Fortran-lang for guiding me throughout the project and giving me the opportunity to work alongside an amazing peer group.

The fortran-lang.org site needed an entire shift of the existing static site generator form Jekyll to Sphinx. I have also integrated internationalization and added support for translating the the site into more than 10 different languages, added a much needed dark theme for the Community, We have also updated and added new documentation to make it easy for the new contributors to join the community. The latest site's code base is more maintainable, easy to understand , contribute to, catering to all the issues in the previous fortran-lang.org site.

Deciding the Project Architecture

The first step of the project was to explore various different static site generators that would be the best fit for our website which had earlier documentation in markdown and kramdown. After various discussions with mentors, Sphinx Static site generator was found to be the best and perfect fit meeting our project requirements and also adding some importrant functionalities that we lacked for in the Jekyll. Therefore, the Project architecture was decided to be consisting of various Sphinx plugins like Ablog, Myst-parser, pydata-sphinx-theme, Sphinx-design, Sphinx-jinja, Jinja 2 and pylint, balck and pre-commit for precommit-hooks.

Building An Entirely New site from Scratch

The first step of this project was to make the entire site in Sphinx from scratch so, that we could remove the old redundant code, dependencies and other existing bugs in the code. So, we Decided to altogether make a new repo so that we could have clean , maintainable site. Thus, after discussion with mentors we decided to get archive the old fortran-lang.org site and to make a new site on sphinx. i had statrted to port the various ssections like learn in learn section we also had to embed the YAML data for various references of the fortran. We also decided to reuse the code of pydata theme's version switcher for implementing language switching across the site by making multiple site builds.

New fortran-lang.org site with Sphinx

Old fortran-lang.org site with Jekyll

Designing the new UI

I designed a prototype framework keeping these requirements in mind. We had to shift to 3 panel view from 2 panel view due to the shinx which inturn also increased our ability to show the various subsections in the learn section.This Design on the current site of fortran-lang.org is a result of numerous discussions and brainstorming with mentors to achieve a clean design with optimal compactness.

Implementing the Contributer Graph

I have Implemented a Interactive Contributor graph which has all the stats with various different tabs and features. it is hosted here Contributor Graph.

Dark Theme

I have implemented the Dark theme to the fortran-lang.org site , so that it looks Great and easy for the new users to join the organisation. I have used pydata-theme theme's implementation with custom modifications.

Dark Theme:

Light Theme:

Packages Section

I have implemented a custom package section in which various packages have been included which have been added in the YAML files in the github repository.

News Section

I have implemented a News section in which monthly newsletters have been shown using ABlog which has been integrated with sphinx and also use it to generate RSS feeds.

Internationalisation

I have implemented a custom Internationalisation switcher using the version switcher of the existing pydata-theme to make a language switcher and also added a build of 10+ languages to localize the site.

Intrinsics Section

I have implemented the pre-existing intrinsic section which includes Intrinsics that have been written in kramdown to port them to myst-markdown.

Contributions to the Project:

Pull Request	Description
#1: Build site from scratch	Initialise the Repository with Sphinx site.
#24: Minor Improvements and features	Incorrect layout for window width > 600 and < 720 pixels Have package, minibook and contributing guidelines as part of the webpage Linting / Stylechecking of Python scripts Should we consistently use MyST-Markdown
#35: Major New features	added pr preview banner for preview builds. (independent of the pydata theme version). added documentation for pre-commit hooks. locked the dependency versions of packages. Formated the html templates. resolved the date error in newsletter of june 2022. enabled build of all translations for build preview resolved button text translated removes all the button properties #29 (for index page) added dependabot for requirements.txt updated translations
#37: Major New features and Bug Fixes	resolves the setup python bug Bump actions/setup-python from 3 to 4 #4 ( there was a bug in v4 which prevented the detection of python version , setting that version of python manually resolves the bug.) resolves the ablog Bump ablog from 0.10.28 to 0.10.29 #36 dependabot pr. github pages url for pr preview. resolves the learn section button translation bug updated the translations for learn section button. shift from custom navbar to original navbar learn section dark theme color fixed. resolves Reduce number of generated strings? #39
#49: Minor features and Pre-commit Hooks	resolves markup code being marked to translation #41 resolves Use markdown formatter for consistent style #43 set prettier in pre-commit hooks prettified all the files. GNU license link in intrinsics.
#117: Minor Bug fixes	resolves typos #56 resolves Automatically delete previews on merge #115 resolves Reduce diff between sphinx-intl and weblate modified po-files #116 resolves rss feed url on nav bar. prettified files. resolves Broken format in intrinsics #118
#137: Minor Features	License Footer Bug fix. Fortran name in index page. webpage Contributor Graph repository. resolve mail box colour resolves workflow delete preview bug update translation po files Bump pydata-sphinx-theme from 0.9.0 to 0.10.1 #136 Bump black from 22.6.0 to 22.8.0 #135
#124: Documentation and Minor Features	resolves Outdated information in docs #120 resolves Weblate is closing spurious "HTML" tags #122 resolves License footers under "Fortran intrinsics" not rendering correctly #130 resole mail box colour documentation for learn section resolves workflow delete preview bug update translation po files

Acknowledgements

On a final note, I'd like to thank all my mentors: Sebastian Ehlert, Rohit Goswami for guiding me through the thought process of building this project and providing their valuable feedback in every stage of the process. I learned a lot about writing quality and maintainable code through this project. I am also grateful to all my peers: Arteev Raina, Ashirwad Mishra, Mohd Ubaid Shaikh and Oshanath Rajawasam as this project was not a stand-alone one and needed cooperation and valuable help from everyone. Lastly, I'd like to acknowledge Google for conducting such an amazing program.

Looking forward to contributing more, in any way I can.