Consolidate documentation about documentation into docs directory #159
Conversation
docs/README.md
Outdated
| "Edit this page" or "Report a problem" links in the header of each page | ||
| at [the online version of this documentation](https://doc.php.net/tutorial/), | ||
| or through [the GitHub repository](https://www.github.com/php/doc-base/). |
There was a problem hiding this comment.
It is no longer in the header but before the user notes.
There was a problem hiding this comment.
This is actually about the 'Edit this page' link on doc.php.net for editing this meta-documentation, not for the regular manual itself.
(There's no 'Report a problem' link on doc.php.net yet, but I plan to add it.)
|
I ripped out all of the out-of-date info on how the manual is built and just direct questions to systems@php.net for now. We can add back info about where the scripts that do the build live, but it looks like not quite all of them are in the systems repo yet. |
|
As someone who started to contribute to the documentation less than a year ago, I can say that this kind of consolidation and clarification on how to contribute is badly needed. Thanks for this! |
| ## How do I find missing documentation? | ||
| Missing functions (no associated XML files) can be found like so (assuming a doc checkout, and PhD is installed): |
There was a problem hiding this comment.
I think this would be the perfect place to add something about how to generate a list of missing constants, functions, methods, etc. with gen_stub.php. Unfortunately I still don't exactly know how to do that but @kocsismate certainly does.
There was a problem hiding this comment.
Sounds like a great addition, but also not something I know how to do, so I can't add it. I'll open a new issue for it if nobody has suggested text by the time this PR lands.
There was a problem hiding this comment.
There is already some documentation at https://php.github.io/php-src/miscellaneous/stubs.html#generating-signatures-for-the-manual.
| descriptions, normal punctuation should be used. Lists, titles, and sentence fragments should not be punctuated with | ||
| a period. Sentences need not have two spaces between them. Commas and apostrophes should be used appropriately. | ||
|
|
||
| ## Personalization |
There was a problem hiding this comment.
It might be useful to separate this page into a general and an English style guide as everything above this line applies to all languages/translations while more or less everything below it applies to doc-en only.
|
Getting this up on new doc.php.net server, we can continue to refine content through other PRs. |
This pulls info that was on doc.php.net and in other places within this repo into one
docsdirectory so everything is in one place.The plan is to have it be published on
http://doc.php.netsomewhere, too (and redirect old/tutoriallinks as necessary), but it's browsable through GitHub, like https://github.com/jimwins/doc-base/blob/clean-up-phpdoc-docs/docs/toc.md