search

php / doc-en

English PHP documentation
501 stars 730 forks source link

Add onboarding information to repo #1148

Open nikic opened 2 years ago

nikic commented 2 years ago

As mentioned in https://github.com/php/doc-en/issues/980#issuecomment-979545901, the repo itself currently doesn't contain any info on how to get started with the docs setup. It would be nice to include information either in the README or CONTRIBUTING.md, so people don't have to search for it elsewhere.

ssddanbrown commented 2 years ago

Along the same lines of easing contribution access, I've put together a docker container with a preconfigured environment for building the docs: https://github.com/ssddanbrown/PHP-Docs-Builder

Not sure if/where it would fit in with this repo (or the doc-base repo) but just sharing it here in the hopes others would find it useful.

hakre commented 2 years ago

@njames: if it helps (ref), I also found http://doc.php.net/tutorial/local-setup.php but relatively late. Until then I kept some notes.

Otherwise I was able to go along starting with checking out the doc-en repository with the knowledge that this is docbook (XML) and that I needed to learn about how the php.net manual php pages are generated.

My Notes

Technically a parenting project with sub-directories pointing to the different git repositories, here a setup to author the English docs, run the docbook pipeline, deploy into the php manual website (which then can be browsed with the PHP development server).

Requirements: php-cli (~7.2+) + extensions + git(1) [+ rsync(1)]

Multiple Repositories:

NOTE: find all repositories in the php org

  • doc-en (-> en) the english documentation
  • doc-base building / docbook base system
  • phd PhD - PHP DocBook
  • web-php, full php.net source

Generating and Publishing the Manual

  1. Generate docbook: \ $ php doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-lang=en
  2. Generate PHP manual: \ $ php phd/render.php -d doc-base/.manual.xml -P PHP -f php
  3. Rsync the PHP manual: \ $ rsync --info=progress2 -a output/php-web/ web-php/manual/en

    NOTE: it is perhaps better to use a symbolic link, web-php suggests this is supported

This setup allowed me to file patches for doc-en as well as for web-php. Configuring VCS ignores is mandatory for web-php when deploing the documentation php files into it (those are a couple and you don't want to commit them).

If it is useful to have onboarding within doc-en, perhaps a getting-started branch that can be checked out via the git-workspace plugin. It could consist of a git submodule setup and a README.md how to go along. It could pin a "known good" setup and close to self-documenting how it works from a checkout alone.

The main branchs' read-me then could contain the information on how to enter the getting-started workspace.