Taming the 'Saurus
Mohan, Divya
Originally having been developed for the open source projects at Facebook, Docusaurus now serves as an easy-to-use tool across many open-source projects. Having worked with it on the Google Season of Docs for transforming Rucio's documentation & as the SIG DOCS lead for LitmusChaos, this talk is an exposition of my experiences with the static site generator. I hope to benefit others looking at migrating to/using this tool with the contents.
 Hello everyone, I am Divya and today I am going to be speaking about taming the source. That specifically focuses on my experiments or rather my experiences with the Torqueous Horus as a static site generator tool. Now I am sure given the number of virtual conferences that we have all attended so far, we pretty much echo the same sentiment that virtual conferences don't just cut it when it comes to the human interaction and to the level of engagement that we have at in-person conferences. So in order to switch things up a little bit, I have sort of come up with a strategy and I hope you folks will play a lot. Now you may ask why I am doing this but I have realized that even with the best efforts on the part of the organizer or the speaker as an attendee it is very difficult for you or for anyone really to actually be sitting at the other end just listening to a person go on and on about a particular project even if it's extremely interesting. So in lieu of that I think you all should be able to see a screen I mean a slide on your screen with a QR code. What I'd like for you all to do is to actually put down your mobile phones and download any QR scan or QR code scanner app. Sorry. Throughout the presentation I have sort of made this the standard that the QR code scanner slide ends up looking similar to this one. So whenever you see this you have to scan the code and see for yourself what I'd like for you to see. So in this case this was supposed to be my introductory slide and the website that leads you to talks more about me. Of course since this was an example I will not actually leave you to read through the introductory bits. I'm Divya and I am a senior systems administrator with HSPC. Alongside my job I love contributing to open source projects like Kubernetes, litmus chaos and I also had the extreme good fortune of working with Sun on the previous year's Google season of dogs. Now going to these open source contributions and the Google season of dogs I was exposed to docuservice as a static side generator tool and I'm hoping you guys will play along with the QR code bit because I really want for you to be engaged in this presentation and to see for yourself the results of whatever I have been working on as projects instead of actually pasting them on the slides in front of you. So without further ado let's talk about some of the cool stuff that I've had the good fortune of working on and they happen to be on the docuservice. So here's the QR code again. Now the first project that I'm going to be talking about is the documentation for Ruseau which is Sun's Exascale data management system. Now what is Ruseau, how it got involved, I mean how I got involved with the project and what is the end result that is what will be visible to you if you scan the QR code. I will be talking about the involvement bit. So Ruseau as I mentioned is an Exascale data management system. It was developed at Sun but it's used across scientific communities irrespective of whether or not they are based at Sun. So it's written in Python and Flask and as part of Google's season of talks 2020 I had the good fortune of working on the documentation for this data management system. More details about the project and what were the expected deliverables can be found on the link here. So if you wish to check that out and if you are interested in actually understanding what was our end goal at the start of Google season of talks 2020 you can visit this link after the presentation is done. So why we chose docuservice because there was documentation system already in place right. So one of the major reasons that we chose docuservice was the introduction of JSX modules in the versions of Ruseau, the previous two might joining Google season of talks. So there was JSX, there was a couple of JSX modules introduced as part of Google season of code and the documentation obviously required support for those JSX modules. Now in the version of docuservice that is there currently there's no JSX support. Let me clarify that but what is the end goal is to migrate to the version 2 which does have this sort of feature and it was not at a stable version when we started off the project. So our short I mean our short term goals are to actually move to version 2 wherein we have JSX support for the documentation. Now another thing that we wanted to achieve was to remove the source code dependency. Now before I joined the project the documentation was heavily dependent on the code base for Ruseau. Now most of it was handwritten like 75% of it was handwritten but 25% of it derived the documentation from the code base that is the Python and Flask code base for Ruseau. So what typically used to happen was that when there were changes in the documentation or introduction of new modules or anything we required that the code base and the documentation be in sync by recompiling the entire tree structure for both of them. So that was an additional task that on the part of the administrator or the maintainer of the repository and that is something we wanted to eliminate by separating the code base for the project and separating the documentation repository. So currently after the Google season of docs we've achieved that and this also contributes to ease of maintenance really because currently a lot of it is in markdown and previously it used to be in RST now restructure, text or RST is not something everyone's familiar with. It's not difficult but it's not something everyone is familiar with as opposed to markdown which is a more common language so to say. So that contributes to the ease of maintenance and setting up a GitHub workflow is also very simple so that was another factor in choosing Docusaurus and the previous documentation was built on sphinx and like I said the search feature in sphinx was very rudimentary and was not up to the mark. This is a no way a criticism but it's just something that I noticed when I was comparing different tools which we could base our I mean which we could implement a documentation on. So Docusaurus has by far the most advanced features for site-wide search implementation which is powered by Alholia search and from an administrator or a maintainer perspective there's not much that a person has to do to implement this or to maintain this once you specify the API key in the configuration file. So those were the list of reasons we chose Docusaurus. Now obviously the project wasn't without its challenges because which project is really. So the original documentation as I mentioned was derived from source code and the static site generator tool previously used with sphinx. So one of the major problems with this was that a lot of the documentation was handwritten because there is that thing right where you have handwritten documentation and you have documentation that's derived from APIs or from a source code. So when we use sphinx as a static site generator your code base is basically how do I put it. So your sphinx documentation for this particular project was basically residing in the same repository as your code base and that sort of was an overhead for the folks who were maintaining the documentation since this was not something that was supposed to be a priority in their minds and converting that documentation to Markdown was a big challenge because everything was in RST and as I mentioned before restructured text prior to the Google season of Docs Friday when it was not something I was familiar with it is a bygone format but I'm specifically not familiar with it and no good RST to Markdown passers available so converting the handwritten documentation to Markdown was a big challenge and deciding which should be converted to Markdown and which should retain the static format was also one of the challenges that we adjust. The next one next couple of challenges are relatively minor because they are things that have been already addressed or are being addressed in future releases. So nested sidebars were difficult implementation in the version one point x whichever version you speak of now it's been addressed in version two and since our ultimate goal is to move towards it too we don't foresee an issue with that specifically. Static file inclusion is one thing you will see as a common theme in future slides as well. Static customizing your static file directly something I think should be a feature for documentation generators so that is one thing that I think has potential to be worked upon and it is being worked upon and has progressed quite a bit in the past couple of months so another feature I'm excited to see. Now we come to another QR code slide again and this is my second project with you know docusaurus as a static file generator tool it is obviously a little different from the previous one and this involves an open source chaos engineering tool cloud native chaos engineering tool named as litmus chaos so if you scan this you will be led to the version you'll be led to the website for the litmus chaos on the docusaurus version one we are migrating to version two in the later half of the year but currently we are you know sort of fixing the last couple of things that we always have to fix after moving to the next version we're doing that bit so currently what you will see is the docusaurus version one but I am going to be talking about the migration bit and how the experiences when we move to docusaurus version two so what is litmus chaos and how did I get involved as aforementioned I am the sick dog sleep for litmus chaos and it's an open source project so we are contributions is how I got involved with the project what litmus chaos is a cloud native chaos engineering tool and for the uninitiated chaos engineering is a discipline wherein you introduce chaos and improve the resiliency and availability of applications to customers so for more details around the project documentation you can visit the GitHub repo that's mentioned on this slide here and for more details about chaos engineering which honestly is a separate topic to you know delve into by itself you can visit to you can visit the website on the screen that is principles of chaos.org so when I joined litmus chaos as a contributor it obviously was on docusaurus already it's not a collective decision that I was part of but recently we were speaking of exploring other options and seeing if there was a better fit for the documentation that we had but we chose to migrate from version one to two instead of going to another tool and the slide details some of the reasons why that choice was made so one as I mentioned in the rucial section as well was the ease of maintenance honestly I generally believe that Markdown is a simpler format to maintain a lot of folks might disagree might might agree I understand but I come from a place wherein I am looking at also engaging contributors in the community and Markdown honestly is a lower entry level barrier for them as well and docusaurus has an easy integration with many of the hosting platforms so it's easier for us as folks behind the scenes to sort of set it all up and set up the GitHub workflows as well now as aforementioned newer contributions are something we are looking at actively and as the project grows we are going to have folks from different countries where probably English is not even the primary language so it feels very non-inclusive to not have multi-language support at this point because it's probably more you know comfortable for folks to read stuff in a native language and gain a better understanding of the product than you know having all of it written in English so that's that's one thing and my personal favorite which may seem like a very silly and stupid reason for continuing to use orcusaurus and migrating to version 2 is the dark light theme switch so sorry so now in the current version that is the version that you'll probably be seeing on your screens after scanning the QR code we are at version 1 so this is not there and as an IT professional I'm very used to having a dark theme on almost everything that I use whether it be my Instagram or whether it be my Twitter I mean these are the things I use as part of my profession but VS code or even GitHub all of it is on dark code so when the documentation that you know I sort of am a part of in building has that feature I'm I'm I'm pretty excited to actually use it so yeah that's that's one of the that's one of the last reasons that I think we continue to use docusaurus and honestly the last bit when I spoke about the dark light themes which it was a widely requested feature from the community as well so I think I'm not really alone in that regard now like with the previous project we also had major challenges in this one so migration was a big activity that we undertook in the last quarter of 2020 and it was one of the major challenges that as documentation team we had faced with docusaurus because till that more or less docusaurus was not a sort of you know pain I mean nothing in docusaurus was a pain point except the nested side pass that I'll address next so by migration was particularly a challenge was due to the lack of adequate documentation now don't get me wrong it's documented but I feel like it's it doesn't have sufficient coverage of the you know various features that are changing in version 2 and what you can expect there are probably a couple of pages and every specific use case is not addressed and I understand coming from a product perspective it's not very feasible to do so but when you are using the product for example the last bit wherein the content rendering changes across versions that was something we struggled with and we thought we were doing something wrong when the content from previous versions didn't show up in the new version but that was just a feature so that's something that I would like you know for documentation as a whole to address because I understand that every specific use case cannot be you know listed down but having a sort of knowledge documentation or a sort of repository wherein you have the commonly listed issues would be a good thing because I don't want to be going to GitHub and filing a PR every time I sort of face a roadblock during migration but everything said and done it was a lot easier once we got to version 2 because there were a lot of cool features as I mentioned before and the nested sidebars also came in so it was a win-win for everyone but migration was a bit of a challenge for us as our documentation maintainers and leads so features I'm excited to see in future versions most of these are already covered so I'll quickly run through them so the static assets directory customization is something I'm really rooting for because I am generally looking forward to actually customizing the static assets directory in both of my projects since it's it's it's a very outdated concept to have on the static folder under the static directory what if I actually want to change it so that's something that I'm looking forward to and a significant amount of work has already been you know done in this regard multiple themes again it's a good to have I wouldn't say it's absolutely necessary but it's good to have and the reason for this being that you are allowed to customize your documentation the way you want it with your own CSS files but I as a documentation lead or as a maintainer for documentation want to be able to choose themes and not actually write them from scratch and expand that little effort so that I want to be able to choose that and happy to report that this work being a progress I'll be slowly in this area as well now sidebars as I mentioned before has been a constant sort of grouse that I've had it's either that the sidebars are not nested or this you know implementation is difficult so auto generated sidebars is something I am really looking forward to because a couple of other open source projects that I work on have sidebars that are auto generated and honestly somebody should not actually have to go out of populate the sidebar configuration file unless there's an explicit requirement so I'll generate sidebars something I'm looking forward to and better migration CLI so a basis my experience in the litmus chaos project I hope for a better migration CLI that or at least better documentation in this regard so as to address at least some of the pain points that folks go through while migration or even you know having them listed somewhere in the documentation for migration will help because if you are just referencing them in one-liners it's not really helpful as a maintainer or as a lead who's undertaking this exercise to actually have just a one-liner about it with no solution so that that is one thing that I would really really appreciate if it was actually improved now that being said I'm at the end of my presentation and I be now open to taking questions so please please if you have any doubts do let me know and thank you so much for all your patience and time and I hope you all stay safe and see you at the end sign
 Hello everyone, I am Divya and today I am going to be speaking about taming the source.  That specifically focuses on my experiments or rather my experiences with the Torqueous  Horus as a static site generator tool. Now I am sure given the number of virtual conferences  that we have all attended so far, we pretty much echo the same sentiment that virtual  conferences don't just cut it when it comes to the human interaction and to the level  of engagement that we have at in-person conferences. So in order to switch things up a little bit,  I have sort of come up with a strategy and I hope you folks will play a lot. Now you  may ask why I am doing this but I have realized that even with the best efforts on the part of  the organizer or the speaker as an attendee it is very difficult for you or for anyone really to  actually be sitting at the other end just listening to a person go on and on about a  particular project even if it's extremely interesting. So in lieu of that I think you  all should be able to see a screen I mean a slide on your screen with a QR code. What I'd like for  you all to do is to actually put down your mobile phones and download any QR scan or  QR code scanner app. Sorry. Throughout the presentation I have sort of made this the  standard that the QR code scanner slide ends up looking similar to this one. So whenever  you see this you have to scan the code and see for yourself what I'd like for you to see. So in  this case this was supposed to be my introductory slide and the website that leads you to talks  more about me. Of course since this was an example I will not actually leave you to read  through the introductory bits. I'm Divya and I am a senior systems administrator with HSPC.  Alongside my job I love contributing to open source projects like Kubernetes,  litmus chaos and I also had the extreme good fortune of working with Sun on the previous  year's Google season of dogs. Now going to these open source contributions and the Google season  of dogs I was exposed to docuservice as a static side generator tool and I'm hoping you guys will  play along with the QR code bit because I really want for you to be engaged in this presentation  and to see for yourself the results of whatever I have been working on as projects instead of  actually pasting them on the slides in front of you. So without further ado let's talk about some  of the cool stuff that I've had the good fortune of working on and they happen to be on the  docuservice. So here's the QR code again. Now the first project that I'm going to be talking  about is the documentation for Ruseau which is Sun's Exascale data management system. Now what  is Ruseau, how it got involved, I mean how I got involved with the project and what is the end  result that is what will be visible to you if you scan the QR code. I will be talking about the  involvement bit. So Ruseau as I mentioned is an Exascale data management system. It was  developed at Sun but it's used across scientific communities irrespective of whether or not they  are based at Sun. So it's written in Python and Flask and as part of Google's season of talks 2020  I had the good fortune of working on the documentation for this data management system. More details  about the project and what were the expected deliverables can be found on the link here. So if  you wish to check that out and if you are interested in actually understanding what was our end  goal at the start of Google season of talks 2020 you can visit this link after the presentation is  done. So why we chose docuservice because there was documentation system already in place right. So  one of the major reasons that we chose docuservice was the introduction of JSX modules in the versions  of Ruseau, the previous two might joining Google season of talks. So there was JSX, there was  a couple of JSX modules introduced as part of Google season of code and the documentation  obviously required support for those JSX modules. Now in the version of docuservice that is there  currently there's no JSX support. Let me clarify that but what is the end goal is to migrate to  the version 2 which does have this sort of feature and it was not at a stable version when we  started off the project. So our short I mean our short term goals are to actually move to version  2 wherein we have JSX support for the documentation. Now another thing that we wanted to achieve was  to remove the source code dependency. Now before I joined the project the documentation was heavily  dependent on the code base for Ruseau. Now most of it was handwritten like 75% of it was handwritten  but 25% of it derived the documentation from the code base that is the Python and Flask code base  for Ruseau. So what typically used to happen was that when there were changes in the documentation  or introduction of new modules or anything we required that the code base and the documentation  be in sync by recompiling the entire tree structure for both of them. So that was an additional task  that on the part of the administrator or the maintainer of the repository and that is something  we wanted to eliminate by separating the code base for the project and separating the documentation  repository. So currently after the Google season of docs we've achieved that and this also contributes  to ease of maintenance really because currently a lot of it is in markdown and previously it used  to be in RST now restructure, text or RST is not something everyone's familiar with. It's not  difficult but it's not something everyone is familiar with as opposed to markdown which is a  more common language so to say. So that contributes to the ease of maintenance and setting up a  GitHub workflow is also very simple so that was another factor in choosing Docusaurus and the  previous documentation was built on sphinx and like I said the search feature in sphinx was very  rudimentary and was not up to the mark. This is a no way a criticism but it's just something that I  noticed when I was comparing different tools which we could base our I mean which we could implement  a documentation on. So Docusaurus has by far the most advanced features for site-wide search  implementation which is powered by Alholia search and from an administrator or a maintainer  perspective there's not much that a person has to do to implement this or to maintain this once  you specify the API key in the configuration file. So those were the list of reasons we chose  Docusaurus. Now obviously the project wasn't without its challenges because which project is really.  So the original documentation as I mentioned was derived from source code and the static site  generator tool previously used with sphinx. So one of the major problems with this was that a lot  of the documentation was handwritten because there is that thing right where you have handwritten  documentation and you have documentation that's derived from APIs or from a source code. So  when we use sphinx as a static site generator your code base is basically how do I put it. So your  sphinx documentation for this particular project was basically residing in the same repository as  your code base and that sort of was an overhead for the folks who were maintaining the documentation  since this was not something that was supposed to be a priority in their minds and converting that  documentation to Markdown was a big challenge because everything was in RST and as I mentioned  before restructured text prior to the Google season of Docs Friday when it was not something I was  familiar with it is a bygone format but I'm specifically not familiar with it and no good  RST to Markdown passers available so converting the handwritten documentation to Markdown was a  big challenge and deciding which should be converted to Markdown and which should retain the static  format was also one of the challenges that we adjust. The next one next couple of challenges are  relatively minor because they are things that have been already addressed or are being addressed in  future releases. So nested sidebars were difficult implementation in the version one point x whichever  version you speak of now it's been addressed in version two and since our ultimate goal is to move  towards it too we don't foresee an issue with that specifically. Static file inclusion is one thing  you will see as a common theme in future slides as well. Static customizing your static file  directly something I think should be a feature for documentation generators so that is one thing  that I think has potential to be worked upon and it is being worked upon and has progressed quite a  bit in the past couple of months so another feature I'm excited to see. Now we come to another QR  code slide again and this is my second project with you know docusaurus as a static file generator  tool it is obviously a little different from the previous one and this involves an open source  chaos engineering tool cloud native chaos engineering tool named as litmus chaos so if you scan this  you will be led to the version you'll be led to the website for the litmus chaos on the  docusaurus version one we are migrating to version two in the later half of the year but  currently we are you know sort of fixing the last couple of things that we always have to fix after  moving to the next version we're doing that bit so currently what you will see is the docusaurus  version one but I am going to be talking about the migration bit and how the experiences when we  move to docusaurus version two so what is litmus chaos and how did I get involved as aforementioned  I am the sick dog sleep for litmus chaos and it's an open source project so we are  contributions is how I got involved with the project what litmus chaos is a cloud native  chaos engineering tool and for the uninitiated chaos engineering is a discipline wherein you  introduce chaos and improve the resiliency and availability of applications to customers so for  more details around the project documentation you can visit the GitHub repo that's mentioned on  this slide here and for more details about chaos engineering which honestly is a separate topic  to you know delve into by itself you can visit to you can visit the website on the screen that is  principles of chaos.org so when I joined litmus chaos as a contributor it obviously was on  docusaurus already it's not a collective decision that I was part of but recently we were speaking  of exploring other options and seeing if there was a better fit for the documentation that we  had but we chose to migrate from version one to two instead of going to another tool and the  slide details some of the reasons why that choice was made so one as I mentioned in the  rucial section as well was the ease of maintenance honestly I generally believe that  Markdown is a simpler format to maintain a lot of folks might disagree might might agree I understand  but I come from a place wherein I am looking at also engaging contributors in the community and  Markdown honestly is a lower entry level barrier for them as well and docusaurus has an easy  integration with many of the hosting platforms so it's easier for us as folks behind the scenes  to sort of set it all up and set up the GitHub workflows as well now as aforementioned newer  contributions are something we are looking at actively and as the project grows we are going  to have folks from different countries where probably English is not even the primary language so  it feels very non-inclusive to not have multi-language support at this point because it's probably  more you know comfortable for folks to read stuff in a native language and gain a better  understanding of the product than you know having all of it written in English so that's  that's one thing and my personal favorite which may seem like a very silly and stupid reason for  continuing to use orcusaurus and migrating to version 2 is the dark light theme switch so sorry so  now in the current version that is the version that you'll probably be seeing on your screens after  scanning the QR code we are at version 1 so this is not there and as an IT professional I'm very  used to having a dark theme on almost everything that I use whether it be my Instagram or whether it  be my Twitter I mean these are the things I use as part of my profession but VS code or even GitHub  all of it is on dark code so when the documentation that you know I sort of am a part of in building  has that feature I'm I'm I'm pretty excited to actually use it so yeah that's that's one of the  that's one of the last reasons that I think we continue to use docusaurus and honestly the last  bit when I spoke about the dark light themes which it was a widely requested feature from the community  as well so I think I'm not really alone in that regard now like with the previous project we also  had major challenges in this one so migration was a big activity that we undertook in the last  quarter of 2020 and it was one of the major challenges that as documentation team we had  faced with docusaurus because till that more or less docusaurus was not a sort of you know  pain I mean nothing in docusaurus was a pain point except the nested side pass that I'll address  next so by migration was particularly a challenge was due to the lack of adequate documentation  now don't get me wrong it's documented but I feel like it's it doesn't have sufficient coverage of  the you know various features that are changing in version 2 and what you can expect there are  probably a couple of pages and every specific use case is not addressed and I understand coming  from a product perspective it's not very feasible to do so but when you are using the product for  example the last bit wherein the content rendering changes across versions that was something we  struggled with and we thought we were doing something wrong when the content from previous  versions didn't show up in the new version but that was just a feature so that's something that I  would like you know for documentation as a whole to address because I understand that every specific  use case cannot be you know listed down but having a sort of knowledge documentation or a sort of  repository wherein you have the commonly listed issues would be a good thing because I don't want  to be going to GitHub and filing a PR every time I sort of face a roadblock during migration but  everything said and done it was a lot easier once we got to version 2 because there were a lot of  cool features as I mentioned before and the nested sidebars also came in so it was a win-win for  everyone but migration was a bit of a challenge for us as our documentation maintainers and leads so  features I'm excited to see in future versions most of these are already covered so I'll quickly  run through them so the static assets directory customization is something I'm really rooting  for because I am generally looking forward to actually customizing the static assets directory  in both of my projects since it's it's it's a very outdated concept to have on the static folder  under the static directory what if I actually want to change it so that's something that I'm  looking forward to and a significant amount of work has already been you know done in this regard  multiple themes again it's a good to have I wouldn't say it's absolutely necessary but it's good to  have and the reason for this being that you are allowed to customize your documentation the way  you want it with your own CSS files but I as a documentation lead or as a maintainer for  documentation want to be able to choose themes and not actually write them from scratch and  expand that little effort so that I want to be able to choose that and happy to report that this  work being a progress I'll be slowly in this area as well now sidebars as I mentioned before has  been a constant sort of grouse that I've had it's either that the sidebars are not nested or  this you know implementation is difficult so auto generated sidebars is something I am really  looking forward to because a couple of other open source projects that I work on have sidebars  that are auto generated and honestly somebody should not actually have to go out of populate the  sidebar configuration file unless there's an explicit requirement so I'll generate sidebars  something I'm looking forward to and better migration CLI so a basis my experience in the  litmus chaos project I hope for a better migration CLI that or at least better documentation in this  regard so as to address at least some of the pain points that folks go through while migration or  even you know having them listed somewhere in the documentation for migration will help because if  you are just referencing them in one-liners it's not really helpful as a maintainer or as a lead  who's undertaking this exercise to actually have just a one-liner about it with no solution so that  that is one thing that I would really really appreciate if it was actually improved now that  being said I'm at the end of my presentation and I be now open to taking questions so please  please if you have any doubts do let me know and thank you so much for all your patience and time  and I hope you all stay safe and see you at the end sign
ttddocusaurus_0_179.png ttddocusaurus_180_1523.png ttddocusaurus_1524_6107.png ttddocusaurus_6108_6371.png ttddocusaurus_6372_6467.png ttddocusaurus_6468_7307.png ttddocusaurus_7308_8843.png ttddocusaurus_8844_12755.png ttddocusaurus_12756_12935.png ttddocusaurus_12936_13403.png ttddocusaurus_13404_13583.png ttddocusaurus_13584_13631.png ttddocusaurus_13632_13703.png ttddocusaurus_13704_13751.png ttddocusaurus_13752_15863.png ttddocusaurus_15864_21287.png ttddocusaurus_21288_23195.png ttddocusaurus_23196_23387.png ttddocusaurus_23388_23759.png ttddocusaurus_23760_24167.png ttddocusaurus_24168_24863.png ttddocusaurus_24864_30875.png ttddocusaurus_30876_32519.png ttddocusaurus_32520_33959.png ttddocusaurus_33960_34199.png ttddocusaurus_34200_35135.png ttddocusaurus_35136_35279.png ttddocusaurus_35280_35327.png ttddocusaurus_35328_37415.png ttddocusaurus_37416_37571.png ttddocusaurus_37572_38267.png ttddocusaurus_38268_38543.png ttddocusaurus_38544_39971.png ttddocusaurus_39972_40067.png ttddocusaurus_40068_40619.png ttddocusaurus_40620_40679.png ttddocusaurus_40680_41047.png
Hello everyone, I am Divya and today I am going to be speaking about taming the source. That specifically focuses on my experiments or rather my experiences with the Torqueous Horus as a static site generator tool. Now I am sure given the number of virtual conferences that we have all attended so far, we pretty much echo the same sentiment that virtual conferences don't just cut it when it comes to the human interaction and to the level of engagement that we have at in-person conferences. So in order to switch things up a little bit, I have sort of come up with a strategy and I hope you folks will play a lot. Now you may ask why I am doing this but I have realized that even with the best efforts on the part of the organizer or the speaker as an attendee it is very difficult for you or for anyone really to actually be sitting at the other end just listening to a person go on and on about a particular project even if it's extremely interesting. So in lieu of that I think you all should be able to see a screen I mean a slide on your screen with a QR code. What I'd like for you all to do is to actually put down your mobile phones and download any QR scan or QR code scanner app. Sorry. Throughout the presentation I have sort of made this the standard that the QR code scanner slide ends up looking similar to this one. So whenever you see this you have to scan the code and see for yourself what I'd like for you to see. So in this case this was supposed to be my introductory slide and the website that leads you to talks more about me. Of course since this was an example I will not actually leave you to read through the introductory bits. I'm Divya and I am a senior systems administrator with HSPC. Alongside my job I love contributing to open source projects like Kubernetes, litmus chaos and I also had the extreme good fortune of working with Sun on the previous year's Google season of dogs. Now going to these open source contributions and the Google season of dogs I was exposed to docuservice as a static side generator tool and I'm hoping you guys will play along with the QR code bit because I really want for you to be engaged in this presentation and to see for yourself the results of whatever I have been working on as projects instead of actually pasting them on the slides in front of you. So without further ado let's talk about some of the cool stuff that I've had the good fortune of working on and they happen to be on the docuservice. So here's the QR code again. Now the first project that I'm going to be talking about is the documentation for Ruseau which is Sun's Exascale data management system. Now what is Ruseau, how it got involved, I mean how I got involved with the project and what is the end result that is what will be visible to you if you scan the QR code. I will be talking about the involvement bit. So Ruseau as I mentioned is an Exascale data management system. It was developed at Sun but it's used across scientific communities irrespective of whether or not they are based at Sun. So it's written in Python and Flask and as part of Google's season of talks 2020 I had the good fortune of working on the documentation for this data management system. More details about the project and what were the expected deliverables can be found on the link here. So if you wish to check that out and if you are interested in actually understanding what was our end goal at the start of Google season of talks 2020 you can visit this link after the presentation is done. So why we chose docuservice because there was documentation system already in place right. So one of the major reasons that we chose docuservice was the introduction of JSX modules in the versions of Ruseau, the previous two might joining Google season of talks. So there was JSX, there was a couple of JSX modules introduced as part of Google season of code and the documentation obviously required support for those JSX modules. Now in the version of docuservice that is there currently there's no JSX support. Let me clarify that but what is the end goal is to migrate to the version 2 which does have this sort of feature and it was not at a stable version when we started off the project. So our short I mean our short term goals are to actually move to version 2 wherein we have JSX support for the documentation. Now another thing that we wanted to achieve was to remove the source code dependency. Now before I joined the project the documentation was heavily dependent on the code base for Ruseau. Now most of it was handwritten like 75% of it was handwritten but 25% of it derived the documentation from the code base that is the Python and Flask code base for Ruseau. So what typically used to happen was that when there were changes in the documentation or introduction of new modules or anything we required that the code base and the documentation be in sync by recompiling the entire tree structure for both of them. So that was an additional task that on the part of the administrator or the maintainer of the repository and that is something we wanted to eliminate by separating the code base for the project and separating the documentation repository. So currently after the Google season of docs we've achieved that and this also contributes to ease of maintenance really because currently a lot of it is in markdown and previously it used to be in RST now restructure, text or RST is not something everyone's familiar with. It's not difficult but it's not something everyone is familiar with as opposed to markdown which is a more common language so to say. So that contributes to the ease of maintenance and setting up a GitHub workflow is also very simple so that was another factor in choosing Docusaurus and the previous documentation was built on sphinx and like I said the search feature in sphinx was very rudimentary and was not up to the mark. This is a no way a criticism but it's just something that I noticed when I was comparing different tools which we could base our I mean which we could implement a documentation on. So Docusaurus has by far the most advanced features for site-wide search implementation which is powered by Alholia search and from an administrator or a maintainer perspective there's not much that a person has to do to implement this or to maintain this once you specify the API key in the configuration file. So those were the list of reasons we chose Docusaurus. Now obviously the project wasn't without its challenges because which project is really. So the original documentation as I mentioned was derived from source code and the static site generator tool previously used with sphinx. So one of the major problems with this was that a lot of the documentation was handwritten because there is that thing right where you have handwritten documentation and you have documentation that's derived from APIs or from a source code. So when we use sphinx as a static site generator your code base is basically how do I put it. So your sphinx documentation for this particular project was basically residing in the same repository as your code base and that sort of was an overhead for the folks who were maintaining the documentation since this was not something that was supposed to be a priority in their minds and converting that documentation to Markdown was a big challenge because everything was in RST and as I mentioned before restructured text prior to the Google season of Docs Friday when it was not something I was familiar with it is a bygone format but I'm specifically not familiar with it and no good RST to Markdown passers available so converting the handwritten documentation to Markdown was a big challenge and deciding which should be converted to Markdown and which should retain the static format was also one of the challenges that we adjust. The next one next couple of challenges are relatively minor because they are things that have been already addressed or are being addressed in future releases. So nested sidebars were difficult implementation in the version one point x whichever version you speak of now it's been addressed in version two and since our ultimate goal is to move towards it too we don't foresee an issue with that specifically. Static file inclusion is one thing you will see as a common theme in future slides as well. Static customizing your static file directly something I think should be a feature for documentation generators so that is one thing that I think has potential to be worked upon and it is being worked upon and has progressed quite a bit in the past couple of months so another feature I'm excited to see. Now we come to another QR code slide again and this is my second project with you know docusaurus as a static file generator tool it is obviously a little different from the previous one and this involves an open source chaos engineering tool cloud native chaos engineering tool named as litmus chaos so if you scan this you will be led to the version you'll be led to the website for the litmus chaos on the docusaurus version one we are migrating to version two in the later half of the year but currently we are you know sort of fixing the last couple of things that we always have to fix after moving to the next version we're doing that bit so currently what you will see is the docusaurus version one but I am going to be talking about the migration bit and how the experiences when we move to docusaurus version two so what is litmus chaos and how did I get involved as aforementioned I am the sick dog sleep for litmus chaos and it's an open source project so we are contributions is how I got involved with the project what litmus chaos is a cloud native chaos engineering tool and for the uninitiated chaos engineering is a discipline wherein you introduce chaos and improve the resiliency and availability of applications to customers so for more details around the project documentation you can visit the GitHub repo that's mentioned on this slide here and for more details about chaos engineering which honestly is a separate topic to you know delve into by itself you can visit to you can visit the website on the screen that is principles of chaos.org so when I joined litmus chaos as a contributor it obviously was on docusaurus already it's not a collective decision that I was part of but recently we were speaking of exploring other options and seeing if there was a better fit for the documentation that we had but we chose to migrate from version one to two instead of going to another tool and the slide details some of the reasons why that choice was made so one as I mentioned in the rucial section as well was the ease of maintenance honestly I generally believe that Markdown is a simpler format to maintain a lot of folks might disagree might might agree I understand but I come from a place wherein I am looking at also engaging contributors in the community and Markdown honestly is a lower entry level barrier for them as well and docusaurus has an easy integration with many of the hosting platforms so it's easier for us as folks behind the scenes to sort of set it all up and set up the GitHub workflows as well now as aforementioned newer contributions are something we are looking at actively and as the project grows we are going to have folks from different countries where probably English is not even the primary language so it feels very non-inclusive to not have multi-language support at this point because it's probably more you know comfortable for folks to read stuff in a native language and gain a better understanding of the product than you know having all of it written in English so that's that's one thing and my personal favorite which may seem like a very silly and stupid reason for continuing to use orcusaurus and migrating to version 2 is the dark light theme switch so sorry so now in the current version that is the version that you'll probably be seeing on your screens after scanning the QR code we are at version 1 so this is not there and as an IT professional I'm very used to having a dark theme on almost everything that I use whether it be my Instagram or whether it be my Twitter I mean these are the things I use as part of my profession but VS code or even GitHub all of it is on dark code so when the documentation that you know I sort of am a part of in building has that feature I'm I'm I'm pretty excited to actually use it so yeah that's that's one of the that's one of the last reasons that I think we continue to use docusaurus and honestly the last bit when I spoke about the dark light themes which it was a widely requested feature from the community as well so I think I'm not really alone in that regard now like with the previous project we also had major challenges in this one so migration was a big activity that we undertook in the last quarter of 2020 and it was one of the major challenges that as documentation team we had faced with docusaurus because till that more or less docusaurus was not a sort of you know pain I mean nothing in docusaurus was a pain point except the nested side pass that I'll address next so by migration was particularly a challenge was due to the lack of adequate documentation now don't get me wrong it's documented but I feel like it's it doesn't have sufficient coverage of the you know various features that are changing in version 2 and what you can expect there are probably a couple of pages and every specific use case is not addressed and I understand coming from a product perspective it's not very feasible to do so but when you are using the product for example the last bit wherein the content rendering changes across versions that was something we struggled with and we thought we were doing something wrong when the content from previous versions didn't show up in the new version but that was just a feature so that's something that I would like you know for documentation as a whole to address because I understand that every specific use case cannot be you know listed down but having a sort of knowledge documentation or a sort of repository wherein you have the commonly listed issues would be a good thing because I don't want to be going to GitHub and filing a PR every time I sort of face a roadblock during migration but everything said and done it was a lot easier once we got to version 2 because there were a lot of cool features as I mentioned before and the nested sidebars also came in so it was a win-win for everyone but migration was a bit of a challenge for us as our documentation maintainers and leads so features I'm excited to see in future versions most of these are already covered so I'll quickly run through them so the static assets directory customization is something I'm really rooting for because I am generally looking forward to actually customizing the static assets directory in both of my projects since it's it's it's a very outdated concept to have on the static folder under the static directory what if I actually want to change it so that's something that I'm looking forward to and a significant amount of work has already been you know done in this regard multiple themes again it's a good to have I wouldn't say it's absolutely necessary but it's good to have and the reason for this being that you are allowed to customize your documentation the way you want it with your own CSS files but I as a documentation lead or as a maintainer for documentation want to be able to choose themes and not actually write them from scratch and expand that little effort so that I want to be able to choose that and happy to report that this work being a progress I'll be slowly in this area as well now sidebars as I mentioned before has been a constant sort of grouse that I've had it's either that the sidebars are not nested or this you know implementation is difficult so auto generated sidebars is something I am really looking forward to because a couple of other open source projects that I work on have sidebars that are auto generated and honestly somebody should not actually have to go out of populate the sidebar configuration file unless there's an explicit requirement so I'll generate sidebars something I'm looking forward to and better migration CLI so a basis my experience in the litmus chaos project I hope for a better migration CLI that or at least better documentation in this regard so as to address at least some of the pain points that folks go through while migration or even you know having them listed somewhere in the documentation for migration will help because if you are just referencing them in one-liners it's not really helpful as a maintainer or as a lead who's undertaking this exercise to actually have just a one-liner about it with no solution so that that is one thing that I would really really appreciate if it was actually improved now that being said I'm at the end of my presentation and I be now open to taking questions so please please if you have any doubts do let me know and thank you so much for all your patience and time and I hope you all stay safe and see you at the end sign
my experiences with the Torqueous Horus as a open source projects like Kubernetes, litmus really. So the original documentation as I static site generator tool previously used with text prior to the Google season of Docs Friday potential to be worked upon and it is being be led to the website for the litmus chaos on the contributions are something we are looking at this is not there and as an IT professional I'm