gregwar / rst Goto Github PK
View Code? Open in Web Editor NEWPHP library to parse reStructuredText documents
License: MIT License
PHP library to parse reStructuredText documents
License: MIT License
Links can be followed by a direct ) , or .
Numbered lists can be defined with #.
Lists can contains empty lines
Dear Grégoire,
thanks a lot for this great peace of code. I´m unsure if this is the right place to ask if not please just close/ignore this issue.
My question is:
As far as I can see /HTML/Document renderDocument() is responsible for the html structure. Further it´s possible to inject css and js in each file. But what would be your recommend way if this HTML structure does not fit my needs? Let´s say I would like to inlude the TOC in every file or to have only the body rendered without head tag .. to include the files in other templates?
Here are my Ideas where but I´m unsure which way to go:
Happy about your input!
Cheers and merry christmas ;)
Toni
Is it possible to support tables with varying colspans like this?
+-------------------+---------------+-----------------------------------------------------------------------------------------------+
| Doctrine | PHP | Database vendor |
| | +--------------------------+---------+----------------------------------------------------------+
| | | Name | Version | Type |
+===================+===============+==========================+=========+==========================================================+
| **smallint** | ``integer`` | **MySQL** | *all* | ``SMALLINT`` ``UNSIGNED`` [10]_ ``AUTO_INCREMENT`` [11]_ |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **Drizzle** | *all* | ``INT`` ``UNSIGNED`` [10]_ ``AUTO_INCREMENT`` [11]_ |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **PostgreSQL** | *all* | ``SMALLINT`` |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **Oracle** | *all* | ``NUMBER(5)`` |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **SQL Server** | *all* | ``SMALLINT`` ``IDENTITY`` [11]_ |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **SQL Anywhere** | *all* | ``UNSIGNED`` [10]_ ``SMALLINT`` ``IDENTITY`` [11]_ |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **SQLite** | *all* | ``INTEGER`` [16]_ |
+-------------------+---------------+--------------------------+---------+----------------------------------------------------------+
| **integer** | ``integer`` | **MySQL** | *all* | ``INT`` ``UNSIGNED`` [10]_ ``AUTO_INCREMENT`` [11]_ |
| | +--------------------------+ | |
| | | **Drizzle** | | |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **PostgreSQL** | *all* | ``INT`` [12]_ |
| | | | +----------------------------------------------------------+
| | | | | ``SERIAL`` [11]_ |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **Oracle** | *all* | ``NUMBER(10)`` |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **SQL Server** | *all* | ``INT`` ``IDENTITY`` [11]_ |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **SQL Anywhere** | *all* | ``UNSIGNED`` [10]_ ``INT`` ``IDENTITY`` [11]_ |
| | +--------------------------+---------+----------------------------------------------------------+
| | | **SQLite** | *all* | ``INTEGER`` [16]_ |
+-------------------+---------------+--------------------------+---------+----------------------------------------------------------+
We are migrating from Sphinx and this is something they seem to support.
Case:
.. slide::
Test
.. image:: /img/something.png
Thnx for RST!
I can't figure out how to write a directive. Directive code:
class Dog extends Directive
{
public function getName()
{
return 'dog';
}
public function processNode(Parser $parser, $variable, $data, array $options)
{
return new Nodes\ParagraphNode('<b>'.$data.'</b>');
}
}
Calling code:
class Thing extends Gregwar\RST\Parser {
protected $dog;
function __construct() {
parent::__construct();
$this->dog = new Dog;
$this->registerDirective($this->dog);
}
}
$parser = new Thing();
$rst = '
Hello world
===========
.. dog:: nothing
:scale: 50
:weight: 68
This is a dog.
That was a dog.
';
// Parse it
$document = $parser->parse($rst);
// Render it
echo $document;
processNode
in Dog
gets the word "nothing" in the param $data. $variable is empty. $options is as expected. processNode
doesn't seem to get the body (This is a dog).
What am I missing?
A tutorial would be useful. I'm willing to write one if I can figure out what's going on.
I have this RST Code
Hello world
===========
But render is plaintext, in <p>Hello world\r\n===========\r\n</p>
I used example from README.md
$parser = new \Gregwar\RST\Parser;
$value = (string)$parser->parse($value);
Now I used the whole sample:
Hello world
===========
What is it?
----------
This is a **RST** document!
Where can I get it?
-------------------
You can get it on the `GitHub page <https://github.com/Gregwar/RST>`_
and what I see:
<p>Hello world
===========
</p>
<p>What is it?
----------
This is a <strong>RST</strong> document!
</p>
<p>Where can I get it?
-------------------
You can get it on the <a href="https://github.com/Gregwar/RST">GitHub page</a>
</p>
a link and bolder is right rendered, but heading is not correctly
I'm trying to parse the Godot Docs without much luck... I tried doing some hacks but it seems to made things worse... What can i do?
This is the file:
And it parses ok in their site but they are using Sphinx:
https://docs.godotengine.org/en/stable/getting_started/scripting/gdscript/gdscript_basics.html
Two days and i'm still trying to fix links...
If a RST document defines a reference which cannot be found:
:ref:RST_is_not_available
the parser stops. Is it possible to just ignore these cases when using builder?
When I tried to parse some documentation that I had written the parser threw an exception that the important directive was unknown. Is it possible to add this?
See http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions for more information on the different admonitions
Hello, I want to parse a documentation with includes, but I only got a message, that an included file doesn't exist: .//book/map.rst.inc It looks like an bug in Environment.php (the ".//" in the path could not be correct).
PHP Fatal error: Uncaught exception 'Exception' with message 'Unknown directive: role' in /Users/kay/Development/rest/vendor/gregwar/rst/Gregwar/RST/ErrorManager.php:17
Stack trace:
I would expect something like:
unknown directive role in file whatever.rst on line 510
Hello,
When Im tryin to create table with diacritic content, it fails and prints characters without diacritis.
It is possible to fix this ? Or any available solution
For example
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
Číslo False False
===== ===== ======
prints:
?íslo T
Hello, could I make some inline directives ?:) something like
I write something and and I'm writting something new
I would like to get something like
I write something and <code> this is my code</code>
And I want it inline
I'm facing what I believe is an issue when using links with this RST library:
When generating links that begin with '/', the resulting output does not match what I would expect as the initial forward slash gets removed from the final HTML link.
Here is an example (using RST v1.0.4):
Source code:
// Load RST parser.
$parser = new Parser();
// Parse input RST text.
$parsed_text = $parser->parse('
This is a link: `My link </my/path/to/link.html>`__
');
$result = $parsed_text->renderDocument();
// Output HTML result.
echo $result;
Expected result:
<p>This is a link: <a href="/my/path/to/link.html">My link</a></p>
Observed result:
<p>This is a link: <a href="my/path/to/link.html">My link</a></p>
Note: When using This is a link: `My link <//my/path/to/link.html>\`__
as input, it does keep one forward slash in the output, but it seems like a workaround that should not be used.
Am I missing anything here?
Best regards,
PAC
Is it possible to support something like this?
Here is some RST text. [1]_
Here is some more RST text. [2]_
.. [1] This is the note about it.
.. [2] This is another note.
The [1]_
and [2]_
turn in to links that anchor down to the list of notes below.
I´m trying to use build() for conversation from rst documents to html.
Unfortunately the output dir stays empty.
error.log does not give useful information – but I found an error method.
How can I use the ->error() (or something else) to get more information what goes wrong
with build?
include_once('autoload.php');
$builder = new Gregwar\RST\Builder;
$builder->build('admin/doc/source/', 'output');
echo $builder->error;
When I use
Installation
------------
**Stable release**
Via the Python Package Index::
$> pip install package
**Development version**
For a simple system-wide installation::
$> pip install -r requirements.txt .
Depending on your system, you may need root privileges. On UNIX-based
operating systems (Linux, Mac OS X etc.) this is achieved with ``sudo``.
For development, especially if you want to test the package from within
the source directory::
$> pip install -r requirements.txt --user -e .
the block after the $> pip install -r requirements.txt .
does not appear to be normal text but considered to be code (although it is regular text).
+-----------------------------------+---------------+-----------------------------------------------------------------------+
| Property | Data Type | |
+===================================+===============+=======================================================================+
| description | string | |
+-----------------------------------+---------------+-----------------------------------------------------------------------+
| author | string | |
+-----------------------------------+---------------+-----------------------------------------------------------------------+
| keywords | string | |
+-----------------------------------+---------------+-----------------------------------------------------------------------+
The equal signs should not appear in the html
Administrator manual
====================
.. only:: html
This chapter describes how to manage the extension from a superuser point of view.
.. toctree::
:maxdepth: 5
:titlesonly:
v1.0.0 came out in 2014, is this library stable enough to declare v1.0.1?
Thanks for the parser. A useful thing!
I defined a dude subdirective. It's similar to the div code:
namespace AppBundle\Service\RstCustomDirectives\Directives;
use Gregwar\RST\Parser;
use Gregwar\RST\SubDirective;
use Gregwar\RST\Nodes\WrapperNode;
class Dude extends SubDirective
{
public function getName()
{
return 'dude';
}
public function processSub(Parser $parser, $document, $variable, $class, array $options)
{
$start = '<div';
if ($class) {
$start .= ' class="'.$class.'"';
}
$start .= '><p>DUDE!</p>';
return new WrapperNode($document, $start, '</div>');
}
}
Here's some test code:
$rst = '
This is a **RST** document! About to div it.
.. div:: indent
This is inside a div.
.. div:: indent
This is a nested div.
.. div:: indent
This is inside a nested div.
.. div:: indent
This is a div after nested divs.
This is predude.
.. dude:: indent
:scale: 50
:weight: 68
This is the first dude.
.. dude:: indent
:scale: 50
:weight: 68
This is your inner dude.
.. dude:: indent
:scale: 50
:weight: 68
This is another dude.
This is post dude. AYE!
';
$dudeDirective = new Dude();
$parser = new Parser();
$parser->registerDirective($dudeDirective);
$document = $parser->parse($rst);
return $this->render(':rst:rsttest.html.twig', [
'base_dir' => realpath($this->getParameter('kernel.project_dir')).DIRECTORY_SEPARATOR,
'parsedHtml' => $document,
]);
There are divs in divs, and that works. When dudes are not nested in dudes, no problem. However, when a dude is nested in a dude, like the inner dude above, the code crashes. Error:
Unknown directive: dude in (unknown) line 6
The message seems to be from $parser->getCurrentDirective()
. $parser->directives[]
doesn't contain dude at that point. However, dude was in $parser->directives[]
earlier, when processing the first div.
Not sure this is relevant: SubDirective->process()
calls $parser->getSubParser();
on line 24. That executes this line on Parser line 74:
return new Parser($this->environment, $this->kernel)
I don't see how the registered directives get passed there. Could that be the issue?
.. ==================================================
.. DEFINE SOME TEXT ROLES
.. --------------------------------------------------
.. role:: typoscript(code)
.. role:: ts(typoscript)
:class: typoscript
.. role:: php(code)
:language: php
.. highlight:: php
Indented lists like:
* A
* B
Should be lists and not quotes
Pretty tables with + - and | should be handled
Embedded URIs should allow for newlines as shown in an example at http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets . The current parsing of links assumes the link is contained on a single line, which can result in empty anchor links. Examples:
Correct when all on one line:
INPUT
`Google <https://google.com>`_
OUTPUT
<p><a href="https://google.com">Google</a></p>
Incorrect when spanning two lines:
INPUT
`Google
<https://google.com>`_
OUTPUT
<p><a href="">Google
<https://google.com></a></p>
Note that the Online reStructuredText Editor (http://rst.ninjs.org) correctly renders the link in both cases.
I think the fix requires Parser.php to have a new 'state' when parsing links to allow for links that span multiple lines.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.