Git Product home page Git Product logo

rst-playground's Introduction

rst-playground

A fully browser-based reStructuredText playground that anyone can use without setting up a server. Try it out at https://waldyrious.github.io/rst-playground.

Motivation

This project was triggered by the two previous playgrounds (http://rst.ninjs.org and https://livesphinx.herokuapp.com) having stopped working as of December 2022, and because I am more used to markdown and too lazy to learn rST properly, so I find myself often needing such a playground where I can try out the syntax and see how it renders. (Also because I've been curious about Pyodide for a while, so it was an opportunity to give it a try.)

More detailed background:

Status

A basic prototype is up and running. The webpage is live at https://waldyrious.github.io/rst-playground. It uses Pyodide to call docutils to convert rST content entered into the <textarea> on the left, and shows the resulting HTML in the <iframe> on the right.

Check the open issues for planned improvements. Pull requests are welcome!

rst-playground's People

Contributors

alessandro-battiato avatar not-my-profile avatar waldyrious avatar

Watchers

avatar avatar avatar

Forkers

not-my-profile sahad-09 alessandro-battiato tssujt

rst-playground's Issues

Support authoring rST directly in the input box

Currently we expect the user to paste or write rST formatted text directly into the plaintext textarea. We could improve on this experience by allowing some convenience rST authoring functionality to the textarea.

One example would be to implement syntax highlighting in the input area, which would signal to users when they are using valid rST syntax. I quite like the approach of LDT (Lightweight Decorator for Textareas), for instance.

Another way to support this flow would be to have an actual toolbar to insert formatting markup, as was the case in the now defunct http://rst.ninjs.org and its predecessor https://livesphinx.herokuapp.com. I'm not so sure about this one, though, as it could drastically increase the complexity of this tool.

Doesn't support multiline strings

Currently there's an ugly hack of using an <input> element (which only supports a single line) because I wasn't able to pass a multiline string from the <textarea> to docutils's publish_string():

rst-playground/index.html

Lines 71 to 72 in f8698e0

publish_string("${input.value}".encode('utf-8'), writer_name='html5').decode("utf-8")
# TODO: figure out a way to pass multiline string (from the textarea)

This means the demo is only useful for single-line rST input, which is clearly inadequate. A proper fix should be implemented to allow using multiline strings and get rid of the <input> hack.

Convert index.html to XHTML

I had initially created the page as a XHTML document, but had to go back to basic HTML because the iframe injection interfered with that. Once the conversion code is working properly, I'd like to investigate going back to XHTML, just to have an extra layer of code structure checking (i.e. the browser itself will warn if the webpage is malformed).

The change would be simply renaming index.html to index.xhtml, and changing <html> to <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> within it.

Relevant code:

rst-playground/index.html

Line 2 in f8698e0

<html><!-- TODO: convert back to XHTML: <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> -->

Consider using Pyscript

Pyscript provides a <py-script> HTML element that could make the code a little more readable. It relies on Pyodide underneath, so no functionality would be lost.

Fix iframe reload issue in Firefox

Currently, reloading the page will load itself nested into the iframe. This appears to be a bug in Firefox.

I tried some of the approaches mentioned in this StackOverflow thread, but didn't manage to get it to work properly.

Relevant (commented-out) code:

rst-playground/index.html

Lines 41 to 46 in f8698e0

// Attempt to prevent caching of the iframe source
// https://stackoverflow.com/a/52507285/266309
// This seems to break the page upon reload...
// var myIFrame = document.getElementById("output-iframe");
// myIFrameUrl = myIFrame.contentWindow.location.href;
// myIFrame.src = myIFrameUrl + '?timestamp=' + new Date().getTime();

Improve styling: add basic UI design

The webpage currently has almost no styling, and could be improved to provide a UI that actually communicates that this is a working, ready-to-use project, rather than an improvised, unfinished demo.

Some ideas:

  • Experiment with the https://github.com/dohliam/dropin-minimal-css switcher, and with the styles listed at https://github.com/dbohdan/classless-css, to find styles that could improve the page
  • Rework the grid layout to be column-first rather than row-first (which would make the form labels be positioned over the corresponding elements in the source as well as in the rendered view). See this and this for possible inspiration
  • Allow the second column to wrap when in tall and narrow screens

Display messages if JS or WASM are not enabled

The index.html file (yes there is absolutely no reason to use .xhtml^^) should contain sth like:

<noscript>This website requires JavaScript.</noscript>

at the top of the website.

And in the JavaScript code we want to check if typeof WebAssembly === 'object' and otherwise do something like alert("This website requires WebAssembly.").

Look into cleaning up docutils' output

As mentioned here:

rst-playground/index.html

Lines 73 to 75 in f8698e0

# TODO: change to publish_doctree() + cleanup + publish_from_doctree()
# (see https://docutils.sourceforge.io/docs/api/publisher.html)
# so that the output can be just the plain inner content and not have to be placed in an iframe

...we are currently using docutils's publish_string() to parse an rST string and produce an HTML string. The resulting HTML is a full page, complete with CSS. I would like to be able to have a cleaner output — just the rendered content, which could then be placed into the <output> element's innerHTML. Of course, this would make the app vulnerable to changes in docutils's output, but a pinned version (#2) or a test suite (#24) should be sufficient to avoid that.

Auto-convert on typing

Instead of a "Run" button, we should simply convert the text automatically whenever the input changes. The experience should be similar to this (incomplete) rST converter: https://seikichi.github.io/restructured/.

One way to achieve this could be using the onsubmit attribute of the form, as was done in an early version of the code that got commented out as the remaining pieces were being set in place:

rst-playground/index.xhtml

Line 15 in da5c919

<!-- <form oninput="html_output.value=rst_input.value"> -->

Note: converting the text automatically would probably require some sort of throttle to prevent running the conversion on every keystroke.

Investigate ways to improve performance/responsiveness

There's currently a slight delay until the page is ready. It might be worth researching whether Pyodide allows pre-bundling modules so that they are loaded at the same time as the Pyodide script itself and not when the Python code is executed.

In any case, there is likely to always be a delay given the complexity of setting up a Python interpreter in the browser, so better UX for while the page isn't ready could also be a good idea.

Add a test suite

This would give us more confidence (other than manually testing the site) when merging PRs. It would also enable automatic version bumps.

Since this is a GUI app rather than a software library or CLI interface, it's likely that we will need some sort of visual testing, e.g. using Playwright, WebdriverIO, BackstopJS, etc. Here's a blog post describing how Wikipedia implemented such a visual regression testing system.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.