phpDocumentor / phpDocumentor/guides
Improve Buffer class
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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