liip / liip/LiipImagineBundle

Update Instructions for Building RST Documentation

Open
#1,433 4 comments 0 reactions 1 assignee View on GitHub

@robfrawley is already working on this.

Since Nov 20, 2021.

Level: Bug 🐞 State: Confirmed Type: Documentation
Dominant language
PHP
Stars
1.7k
Forks
386
Avg merge
1d 10h
Merged PRs (30d)
3

Description

Problem Details

The symfony/symfony-docs project has changed their RST documentation build procedure from a Python and Sphinx compilation process to a PHP application in symfony/symfony-docs#16068.

The new RST documentation build process relies on an internal (and not officially supported, but MIT licensed) PHP command-line app in the symfony-tools/docs-builder project, which internally utilizes the doctrine/rst-parser library for RST parsing.

Over the next week or two, I will be updating the Wiki instructions for this bundle to use the new symfony/symfony-docs RST documentation build procedure, and will further provide a pull request to address any changes needed within the project itself to facilitate the new RST compilation procedure.

If anyone has any feedback as to how our RST build instructions could otherwise be improved, or if anyone has any input as the primary goals of this report, please feel free to comment. Otherwise, I will provide updates here as I progress.

Template Questions

Preconditions / Steps to Reproduce
  1. Follow the RST documentation compilation instructions from github.com/liip/LiipImagineBundle/wiki/Building-RST-Documentation.
Expected Result
  1. The bundle RST documentation is compiled into HTML.
Actual Result
  1. An large number of steps fail due to the instruction's reliance on symfony/symfony-docs files and build process.

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.