Docs: Move DevEnv to own section for docs #23593
Conversation
|
Size Change: 0 B Total Size: 1.14 MB ℹ️ View Unchanged
|
|
Title: Docs: Move DevEnv to own section for docs "This moves the Development Environment documentation out of the Create a Block tutorial and to its own section. This allows for easier linking from elsewhere. Plus allows for simplifying the Create a Block tutorial, with linking over the the DevEnv as a pre-requisitite." "It also gives a section to expand more on the Development Environment setup. I created it as its own directory so if we want to break each piece out—Node, WordPress Environment, and Code Editor—to its own page, there is space for it to grow." "This new development environment is related to the Contributors Getting Started Guide. The contributor guide docs are specific to contributing to Gutenberg, whereas the guide in this PR is specific to plugin developers extending the block editor." EDIT Sunday 5th of July. I find the above sentences very confusing. We should add a new Creating a Development Environment as the first section under Developer Documentation. Rephrasing the above sentences that you wrote. Btw there is no need to mention extending the block editor here in this PR. As it was already mentioned in the first sentence in this PR. |
|
Going through Development Environment docs. "A development enviornment (typo) is a catch-all term for the setup on your computer to work." "The script npx is installed with npm and is used to run packages not yet installed, we will use this to bootstrap a block." "Here are the quick instructions to install using nvm, ..." Run the following on the command-line to install nvm: A message might show up:
In terminal it might say this: Click Install to open the Mac Automatic Update, and the command line developer tools will be downloaded and installed. Run the Node Version Manager install command line again: This time there should be no error message as the Mac command line developer tools have been installed. This is what I saw: After installing nvm, you now need to install the latest version of node, run: This is the message I received: If there is an error running the above command line code on the Mac then you might need to create the required file zshrc. To do so type This is what I noticed in terminal after having also tried to install nvm. So here it stopped up, and I am not certain where to go from here. NB!!! Continuing.... This is what I saw: Checking to see if node and npm have been installed. "After confirming that the prerequisites are installed, install wp-env globally from the command-line using:
Rephrasing the above sentence: After you have installed Docker go ahead and install wp-env globally from the command-line using: This is what I saw in terminal: To confirm it is installed and available, run: It looks like wp-env made a WordPress local site, but where is it located? If I need to remove nvm and Docker to start again how do I do so? Alternatives A couple of alternatives that might be easier, since they do not require Docker install and setup. Plugin step. |
docs/designers-developers/developers/tutorials/create-block/wp-plugin.md
Outdated
Show resolved
Hide resolved
|
@paaljoachim Thanks for the feedback, I need to go through each still but for future reference, Github has a suggestion and review tool that allows submitting feedback in context with the lines of code. See this Github documentation for more info Using the suggestion tool makes line edits, spelling and also associates your name with the change. |
|
@paaljoachim Thanks for the feedback, I updated the docs addressing your points. I modified slightly so it includes instructions for additional environments besides the Mac. Also, to note the alternative environment is only for Docker, the headings have it under that section. Node is still required and there is no alternative, only different methods to installing which are already linked to above. |
docs/designers-developers/developers/tutorials/devenv/readme.md
Outdated
Show resolved
Hide resolved
| We will need a place to work and tools for creating a block, this is often referred to as the development environment. The three main pieces needed for our development environment are: | ||
| The development environment setup guide is for setting up your local development environment for JavaScript development; creating plugins and tools for extending WordPress and the block editor. | ||
|
|
||
| A development environment is a catch-all term for the setup on your computer to work. The three main pieces needed for our development environment are: | ||
|
|
||
| 1. Node/NPM Development Tools | ||
| 2. WordPress Development Site | ||
| 3. Code Editor | ||
|
|
There was a problem hiding this comment.
The short guide.
In terminal - Mac, Windows or Linux.
Install nvm:
curl -o- https://github.com/raw/nvm-sh/nvm/v0.35.3/install.sh | bash
Quit and restart terminal.
Install node:
nvm install --lts
Download and install Docker. Startup Docker (?) ...
In terminal.
npm -g install @wordpress/env
Check to see it has been installed:
wp-env --version
Do something (?)
Then in terminal:
wp-env start
You should now have a local development environment in place. If something does not work then check the uninstall guide to remove and start over. - @mkaz and @noahtallen it would be good to have a section for uninstalling all that we have installed. To start over if needed.
There was a problem hiding this comment.
The do something step is from the Create a Block tutorial, on generating the plugin directory see wp-plugin.md.
npx @wordpress/create-block gutenpride
cd gutenpride
wp-env start
The create block script creates a plugin directory, you run the wp-env start from within that directory.
There was a problem hiding this comment.
you can uninstall wp-env like so:
- run
wp-env destroyto destroy the local environment data for a specific projest - run
npm uninstall -g @wordpress/envwill uninstall the npm package, but will not remove any environment data
There was a problem hiding this comment.
The do something step is confusing as we are having nice and logical steps on what to do in terminal to setup a local WordPress development. I expect the do something step will then create the local WordPress development site which we can then easily access. I am saying the same thing just below. We should not refer to another tutorial as that information can come later.
There was a problem hiding this comment.
Thanks Noah! Btw how do we test to see that all of it is actually uninstalled?
Having uninstall information (as you added) and checking to see that it is uninstalled would be helpful.
There was a problem hiding this comment.
If it is actually uninstalled, then wp-env start will result in an error like "command not found". Additionally, if you destroyed your environment, the command docker ps -a, which shows a list of local environments, will not display environments associated with the local environment that was deleted.
Verifying that the environment was properly uninstalled is kind of complicated because you have to understand how Docker works and how wp-env works under the hood, since several different things are cleaned up when you run wp-env destroy
There was a problem hiding this comment.
I am thinking as long as one gets the error messages one is supposed to get then that would be the confirmatation that it is uninstalled.
| ``` | ||
|
|
||
| The `wp-env` script is used to create a Docker WordPress environment, to use start from your plugin directory—if you are following the create block tutorial, this would be in the generated directory. | ||
|
|
There was a problem hiding this comment.
It is confusing going from working in terminal to suddenly mentioning the plugin directory.
Where is the plugin directory? We need a step that goes from checking the wp-env to locating the plugin directory and then running wp-env start. This needs clarification.
"...if you are following the create block tutorial, this would be in the generated directory."
This seems out of context. As the context is setting up a local dev environment to be used with creating a plugin and/or contributing to Gutenberg.
(I added a similar comment in the below solved comment thread, but as it got hidden I am adding it again here.)
There was a problem hiding this comment.
I'm not sure setting up a dev environment with no context makes much sense. There is a reason you are setting up an environment, the most likely is for developing a plugin or theme. If you are following the create a block tutorial it provides the context in that tutorial here.
Otherwise, you might of come to this page wanting to setup an environment to create a plugin, so you would have that in mind already.
There was a problem hiding this comment.
We has this introduction:
"The development environment setup guide is for setting up your local development environment for JavaScript development; creating plugins and tools for extending WordPress and the block editor."
This is how I understand it:
Setup a local WordPress development site for creating own plugin and/or contributing to WordPress/Gutenberg. (That is the context.)
"If you are following the create a block tutorial it provides the context in that tutorial here."
As the doc we are working on right now is the very first tutorial for setting up a local dev site I find it confusing that someone would be following the next tutorial in the series so to speak. As the tutorial we have now would be a prerequisite for the block tutorial. Having a side path to tutorial 2 seems strange at this stage.
docs/designers-developers/developers/tutorials/create-block/readme.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/readme.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/devenv/readme.md
Outdated
Show resolved
Hide resolved
|
|
||
| * Check out the [Notices Tutorial](/docs/designers-developers/developers/tutorials/notices/README.md) to learn how to display informational UI at the top of the editor. | ||
| - See the [Meta Boxes Tutorial](/docs/designers-developers/developers/tutorials/metabox/readme.md) for new ways of extending the editor storing and using post meta data. |
There was a problem hiding this comment.
Unrelated to this PR, but can we move Meta Boxes Tutorial further? :)
Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
Adds an additional link in JS tutorial to the new development environment section, with regards to installing using nvm. Plus includes a bit of markdown linting.
Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
|
I think there are some misunderstandings going on right now. I am kinda saying the same thing over and over again in my direct file comments. I am still stuck at I have mentioned these things in various ways... This documentation is about as I see it creating a foundation for a user to develop their own plugin and/or contribute to WordPress/Gutenberg. At the end of the tutorial options for going to Create A Block, Contribute to WordPress Core and/or Gutenberg should be added. As the base foundation for developing with WordPress is in place. I just had to add the above comment as a comment directly to this issue, as I feel that comments in the file can get a bit lost. Ps after we have landed this tutorial and I have a working local WordPress development setup then I can move on to testing out how to contribute to Gutenberg tutorial and the Create a Block tutorial. As I am the first test person so to speak who does not know a lot about coding who is going through this. A designer who wants to get into coding. |
|
This page is a supplemental page to the Create a Bloc tutorial, it was moved out so we can link to it from other tutorials and expand on it the section with additional info that any other tutorial can reference. The command you are trying to run must be run from a plugins directory. The error message says this also. I'll update the instructions but once you have wp-env installed and confirmed you can do: |
Description
This moves the Development Environment documentation out of the Create a Block tutorial and to its own section. This allows for easier linking from elsewhere. Plus allows for simplifying the Create a Block tutorial, with linking over the the DevEnv as a pre-requisitite.
It also gives a section to expand more on the Development Environment setup. I created it as its own directory so if we want to break each piece out—Node, WordPress Environment, and Code Editor—to its own page, there is space for it to grow.
This new development environment is related to the Contributors Getting Started Guide. The contributor guide docs are specific to contributing to Gutenberg, whereas the guide in this PR is specific to plugin developers extending the block editor.
See: #22831
How has this been tested?
Documentation, confirm links work and docs make sense.
View the rendered version on branch here
Types of changes
Documentation