Wagtail Guide - Coen van der Kamp

Speaker 1: So my talk is about Wagdo Guide. My name is Koen van der Kampen and I work at For Digits. And for Digits is a Python shop. and we work with Django and WagTil and most of our Python application run in the browser. So I'm a Python developer. I'm also a Wagtail Core team member And I'm also uh the organizer organizer of Actospace, the Netherlands. And um here's the big announcement. Um Rectal Space NL is is happening. The conference is 15th to 17th of June and we'll have a full event with sprint and talks. And you can also sign up for talks only. So Wagdil. space is the website that lists all Wagdil space events and 2022 is

Speaker 1: the Dutch version. I'll share the link. No worries. First look at my talk and after that sign in for our event. So back to WacDo Guide. The initial ID is a user guide for content editors. and documentation on how to use your uh Waxel site. That's the the output. And um I like it to be an installable package that um Python shops like ourselves can use and have documentation uh to present to our clients. So not only send uh login credentials and URL, but also have a document that the client can read to get started. So

Speaker 1: the initial idea was born in uh during a sprint at Torchbox in Bristol, UK. in 2020 and um the idea got shelved. I forgot about it. And then recently um there was a discussion about the editor's guide as a separate repository or website. And then I thought I have to revise my ID and uh look it up, see if it's still uh something we can use. So if you don't know the Wecto Editors Guide, it's this section in the Wecto documentation. And it's a wall of text. So is my product a replacement for uh the editors

Speaker 1: guide? No, it is not. It's intended as a package for in your own Recto site. It's intended for your clients, it's intended to be uh a getting started uh tutorial or how-to guides. It's in no means um trying to be complete and explain everything about Wagtail. Can it be used to uh help building this new section of the record documentation? Yeah, maybe it might be useful. So um yeah, I'm reiterating myself. Um installable package, getting started tutorial, and the how-to dot dot dot is um yeah, you can fill that in yourself. Um it's intended to uh give you the tool to make your own how-to

Speaker 1: guide guide. The targeted audience are uh content editors, people who get started with Wagtail. and uh moderators and administrators that have to do more complex things, maybe, but uh not that much. So in this talk, I'm gonna show you how to install the package and then uh configure it. Um also how you can customize it and there's a dotted line because You don't have to customize if you like how it is, you can use it like that. If you want to extend it or change something, you can there's the possibility to do that. And then the product vector guide has a built output, but you still have to use that output yourself. You have to serve it or

Speaker 1: do something useful with it. So right to guide. Um let's look at the output. This is um Markdown uh MK docs, markdown uh docs. And um it has here the the instructions how to log in and it made a screenshot of uh a vector site and filled in the fields. Also highlighted the element that you have to click. So all this stuff you can define and then it makes screenshots and shows it. The default, this is the default, will give you this getting started guide and also a demo page with all the elements you can create, like paragraphs, audit and unordered list, code.

Speaker 1: images of cats, screenshots with the browser or screenshots without a browser, and also highlight an element. So let's dive a little bit deeper and go to the code. To install it, you have to just pip install Wagto Guide. It's not on PyPI yet, but if you go to the GitHub page, it has the instruction how you can install from GitHub. And then you've got Wacto Guide included. And um this makes you uh give gives you a command, a management command, the build guide. And if I do this It makes um a database and starts up your browser

Speaker 1: and takes some screenshots And uh this output of this all goes into the documentation directory and you've got images and also uh the markdown So you've got the demo page and uh an index page. Um yes, up next I've got something on the screen. Okay. You can also define uh chapters for your guide. And um One of those is uh home getting started.

Speaker 1: No, let 's revert that. Um Let's customize the site first. So I've got here The base HTML of the Wagtail admin and it overrides the branding icon, the logo. And um I've got also whack the hooks uh file and I uh register an element cars. And then in um Yeah, this. So if I run the guide now, this will take a moment. Open up a browser again

Speaker 1: Let me change one more thing. Markdown docs has this definition of how which chapters are there and how they look. And you can change that quite easily. And if I now go back to the documentation, it changed. The look is different. I've got getting started. I also have my icon. And also got my care menu. So now the documentation is about my site. Let's go to base again. And now I've got here a home guide getting started. This is a callable that um you can use to um define your own

Speaker 1: guide what it should do. So we've got a markdown factory, it generates the index uh markdown file the title of this page is getting started and the documentation first paragraph is this and then there's a heading and um a list and here I create some content. A user is created and with a live server I go to a login URL and fill in the username and the password. and then find the login button and click it. And uh after that, um I don't want to rest of my default uh guide, I want to show that there's an edit bird in the front end of the site. So I navigate to the front end.

Speaker 1: to the root URL and uh I'll highlight the edit bird and then I also click the edit bird and um you see that the menu opens so Let's do this. Again, the database is created, browsers open, screenshots are taken. And uh documentation is updated. So now we've got the front end with the highlight of the edit bird and the menu open So the output now is Markdown, but

Speaker 1: these factories that create The documentation can also be something else. They could also create uh restricted text RST or uh anything else, and um then I thought of hey, maybe we can also create video So I've got now vector guide video getting started. And let's see what this does Again , database created, sites run, screenshots are taken And this takes a little bit more processing.

Speaker 1: So um there's text to speech and now it starts creating the video. So we can all look at the progress bar, but we can also look at Recto Guidecode which is might be a little bit more interesting. So this is build guide management command. It calls PyTest. And uh the way it works is that uh the main test gets a live server and a driver. The driver is the thing that controls the browser and some settings. And here we just call each Weg to guide chapter setting as a callable. We import the string and we call it with the live server and the driver. And with that it calls everything you configure in your settings.

Speaker 1: So uh this finished. I've now a video file, and um yeah, let's see uh how it looks.

Speaker 2: Open a browser and go to slash admin. Enter your username and password. Click sign in. Welcome to the administrative interface or admin for short. This first page is called the dashboard, it shows a summary. The gray bar on the side is the sidebar. Wherever you are, you can always click the logo to navigate back to the dashboard Use search to find content. The main navigation contains pages, images, and documents. In reports you will find an audit trail and other reports. In Settings you can manage users and configure your site. Manage your personal details and preferences in the Account Settings menu.

Speaker 2: The logout option is in Account Settings. Yeah, I don't know.

Speaker 1: This was my talk about the vector user guide, and I'm happy to answer any questions.

Speaker 3: You couldn't hear it, but there was uh tons of applause in the actual room. That was a very, very cool demo, Cohen. Um And we did have one question that star uh off the top. Wanted to know more about your uh development process and the code behind how this works.

Speaker 1: Yes, um I can show a little of that. Um first of all, uh there are some ingredients. Of course, you saw me run the management command. And behind the scene, it just runs tests. So it's PyTest. And we also created content with fixtures. There's this live server and Selenium. Selenium is a Chrome driver that controls the browser and that takes the screenshots. And the output is then marked down. The static site builder itself that I showed isn't included. It's like uh the the um an external package and all that combined is the user guide and i can show some code because i i showed it really really quick

Speaker 1: Um py test you can just call with um a location and directory And then it runs all the tests in that directory. So here I look up the current directory of this installed package. And um look all all the tests who are there. And there's just one test, there's one main test. And this test um looks up the chapters and calls the chapters one by one. And a chapter like that is This a getting started, it receives the live server and the driver, and we've got the markdown factory. And this factory is a context manager. The context manager works in

Speaker 1: um uh when you call it with the with statement. Um I think a lot of people do this when they open up files. You are sure if you open up a context manager, an action is run when when all the the indent stops and the and the code block closes. So I've got here this doc and uh I just write all these elements to this document and I'll have to look at the markdown factory. Can I jump to that? Nope. Um let's take the video. I don't know the way in my own code. Factories.

Speaker 1: Here we go. So the markdown factory, when you enter it, it returns itself. And when you exit it, it opens up a file, which is and writes to this file name. The self-file name is something that it got on the init And then it just starts writing the code blocks. And every code block, like uh uh a heading, is just a piece of text. So the markdown for uh heading is uh Two signs and the content. And all these blocks are just stored here in the on the context manager. And when you close it, it's written to a file. And the same is for a video only the processing in the end is a little bit more complex

Speaker 1: on exit. It just creates a video file. and and creates the audio with text-to-speech. So that was the long answer. Maybe there are other questions

Speaker 3: Thanks so much. Do we have more questions in the audience or on Zoom? uh when you try to set this up with some sort of automation um

Speaker 1: like having you know every time you kind of make an update have to run a new

Speaker 3: Have you ever tried to set this up with some type of update in the second half? Automation. And some type of automation.

Speaker 1: Not sure if I understand the correct uh the question. Yeah. The the automation of the of the of creating script

Speaker 3: Yes.

Speaker 1: Yes. Um yeah, there's uh Selenium browser plugins that you can use. to uh record your action in the in the screen and the and the way I use it right now is uh most of the times I just set a breakpoint. somewhere in the code and then uh run the test and then I get the breakpoint in the browser. The browser just stops there and then I can inspect the HTML and just type in my terminal the instructions that I want to try out. So uh that's the way I work currently. Uh but I can I imagine that uh recording your actions in a browser is uh perfectly fine if it out outputs uh the selects that you need

Speaker 1: um then you're halfway there

Speaker 3: Awesome. And we were also interested in automation on updating. Anytime it updates, could there be an integration of the process to update the documentation every time there's an update?

Speaker 1: Yes, that's a good question. I didn't figure that out uh yet because uh I just worked to uh against the current stable branch. But I imagine that I will release packages with the same version as Wagtail. So every time Wagtail updates, there's a new release of WagtailGuide, and then all the selects are updated to fit the new wagtail and um yeah that's a way to get around it so then you can run the management command again against your updated site and you just get new documentation

Speaker 3: Thank you. Do we have any more questions from in the audience or on Zoom? We have time for about two more questions. I think it was slow so I can repeat it. Is there a wagtail guide for setting up wagtail guides? Is there a wagtail guide for setting up wagtail guides? Where do we go?

Speaker 1: The documentation on the documentation generator is not there yet. I created this a month ago and I worked on it two days ago, seven days ago, and that's about it. There's a comprehensive README and it will get you started with everything you need. So that that's some documentation, but I I would love to create a documentation site that also showcases uh the output And also the instructions of working with Rector Guide itself. But that's on my to-do list.

Speaker 3: It's hard to describe how excited the room was. I mean, everyone I just really appreciate that. So more to do as there always is, but this is fantastic talk. I think we can probably take uh maybe one more uh question. If anyone in the room or on Zoom has one.

Speaker 1: Yeah, I I would like to say that pull requests and contributions are welcome. So if you if you're uh enthusiastic about this and you can see some use for it in your own company. and to help your own clients uh yeah contribute.

Speaker 3: I have two two questions. Is the text-to-speech available in languages other than English?

Speaker 1: Um I used the text-to-speech from Mozilla and uh they have Spanish and some other languages. I don't uh think they have uh Dutch, but they have they have a few languages. Uh yeah. So um Not only English, but I don't know which languages they provide. But basically you you could adapt um the generators themselves to use something else. I now run a document a Docker container to handle the text to speech. Um yeah, it would be easy to uh run it against some other

Speaker 1: tool to get your audio files.

Speaker 3: Awesome. We have one more. Uh are

Speaker 4: there any plans to start using this? Maybe back till three For example.

Speaker 3: Are there any plans to start using this, for example, in Wagtail three?

Speaker 1: Um What I would like to have uh in Wagtail is uh a menu item that you can click and then see your own documentation. Um so I would say it would should work in any um Wagdle version. Um yeah. I intend also to update the package when a new uh Wagdle release is there. So um yeah It will work in write till free. So

Speaker 3: this is the last talk before lunch. And so if you wanted to continue to have more conversations about this really awesome. package of this talk, feel free to chat on Slack. And I'm going to introdu uh bring up Tim and Vince to chat a little bit more.

Speaker 4: We just have one small thing. Thanks so much, Cohen. Round of applause for Cohen. That was amazing.

Speaker 1: Thank you. Bye-bye.