phpDocumentor / phpDocumentor/guides

Improve Buffer class

Open
#239 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
PHP
Stars
36
Forks
22
Avg merge
2d 2h
Merged PRs (30d)
24

Description

Right now we have a number of locations using the buffer class to collect lines from the documents to parse them as blocks. These blocks are always indented. When consuming this buffer we need to remove the initial indentation of the block to be able to process the lines are normal lines.

We want the buffer to be responsible for this un-indenting part. To centralize the way we are doing this. The complexity here is that the indentation of a block may defer per situation. and can be something between 2 or PHP_MAX_INT spaces.

Locations where to do this improvement:

This method removes the indenting. Based on the first line of a block.
\phpDocumentor\Guides\RestructuredText\Parser\Productions\BlockQuoteRule::normalizeLines

Here I do something simular for lists
packages/guides-restructured-text/src/RestructuredText/Parser/Productions/ListRule.php:107
packages/guides-restructured-text/src/RestructuredText/Parser/Productions/EnumeratedListRule.php:109
Definition lists: packages/guides-restructured-text/src/RestructuredText/Parser/Productions/DefinitionListRule.php:99

See https://github.com/phpDocumentor/guides/pull/225 for the original discussion.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading BlockQuoteRule::normalizeLines and the indentation handling at the listed lines in ListRule.php, EnumeratedListRule.php, and DefinitionListRule.php. Compare their behavior with the discussion in pull request 225, then verify that indentation removal is centralized in the buffer and that all four parsing cases still process their block contents correctly.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.