joshua/dash-docs
1
0
Fork 0
mirror of https://github.com/seigler/dash-docs synced 2025-07-26 17:26:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Add 'Setting up your environment'

Browse source
This commit is contained in:
Will Binns 2017-02-28 20:34:00 -06:00
parent d7a015a77b
commit c78a7e8449
No known key found for this signature in database
GPG key ID: 302EBEAEEB74A404
2 changed files with 192 additions and 184 deletions
Download patch file Download diff file Expand all files Collapse all files

184
README.md
View file

@ -60,190 +60,6 @@ You can always report problems or help improve bitcoin.org by opening a [new iss
[full node page]: https://bitcoin.org/en/full-node
[write new documentation]: #developer-documentation
### Previewing
#### Preview Small Text Changes
Simple text changes can be previewed live on bitcoin.org. You only need to click anywhere on the page and hold your mouse button for one second. You'll then be able to edit the page just like a document. Changes will be lost as soon as the page is refreshed.
#### Build The Site Locally
For anything more than simple text previews, you will need to build the
site. If you can't do this yourself using the instructions below, please
[open a pull request][pull request] with your suggested change and one
of the site developers will create a preview for you.
To build the site, you need to go through a one-time installation
procedure that takes 15 to 30 minutes. After that you can build the
site an unlimited number of times with no extra work.
##### Install The Dependencies
Before building the site, you need to install the following
dependencies and tools, which are pretty easy on any modern Linux:
**Install binary libraries and tools**
On recent versions of Ubuntu and Debian, you can run the following
command to ensure you have the required libraries, headers, and tools:
sudo apt-get install build-essential git libicu-dev zlib1g-dev
**Install RVM**
Install RVM using either the [easy instructions](https://rvm.io/) or the
[more secure instructions](https://rvm.io/rvm/security).
Read the instructions printed to your console during setup to enable the
`rvm` command in your shell. After installation, you need to run the
following command:
source ~/.rvm/scripts/rvm
**Install Ruby 2.0.0**
To install Ruby 2.0.0, simply run this command:
rvm install ruby-2.0.0
Sometimes this will find a pre-compiled Ruby package for your Linux
distribution, but sometimes it will need to compile Ruby from scratch
(which takes about 15 minutes).
After Ruby 2.0.0 is installed, make it your default Ruby:
rvm alias create default ruby-2.0.0
And tell your system to use it:
rvm use default
(Note: you can use a different default Ruby, but if you ever change
your default Ruby, you must re-run the `gem install bundle` command
described below before you can build the site. If you ever receive a
"eval: bundle: not found" error, you failed to re-run `gem install
bundle`.)
**Install Bundle**
When you used RVM to install Ruby, it also installed the `gem` program.
Use that program to install bundle:
gem install bundle
**Install the Ruby dependencies**
Ensure you checked out the site repository as described in [Working with
GitHub](#working-with-github). Then change directory to the top-level of
your local repository (replace `bitcoin.org` with the full path to your local
repository clone):
cd bitcoin.org
And install the necessary dependencies using Bundle:
bundle install
Note that some of the dependencies (particularly nokogiri) can take a
long time to install on some systems, so be patient.
Once Bundle completes successfully, you can preview or build the site.
##### Preview The Site
To preview the website in your local browser, make sure you're in the
`bitcoin.org` directory and run the following command:
make preview
This will compile the site (takes 5 to 10 minutes; see the [speed up
instructions](#fast-partial-previews-or-builds)) and then print the a message like this:
Server address: http://0.0.0.0:4000
Server running... press ctrl-c to stop.
Visit the indicated URL in your browser to view the site.
##### Build The Site
To build the site exactly like we do for the deployment server, make
sure you're in the `bitcoin.org` directory and run:
make
The resulting HTML for the entire site will be placed in the `_site`
directory. The following alternative options are available:
## After you build the site, you can run all of the tests (may take awhile)
make test
## Or you can build the site and run some quick tests with one command:
make valid
## Or build the site and run all tests
make all
#### Fast Partial Previews Or Builds
In order to preview some changes faster, you can disable all plugins and
languages except those you need by prefixing the `ENABLED_LANGS` and
`ENABLED_PLUGINS` environment variables to your command line. For
example, do this to disable everything:
## Fast preview, takes less than 30 seconds
ENABLED_PLUGINS="" ENABLED_LANGS="" make preview
## Fast build and tests, takes less than 50 seconds
## Some tests may fail in fast mode; use -i to continue despite them
ENABLED_PLUGINS="" ENABLED_LANGS="" make -i valid
Then to enable some plugins or languages, you can add them back in.
For example:
## Slower (but still pretty fast) build and test
ENABLED_PLUGINS="events autocrossref" ENABLED_LANGS="en fr" make -i valid
Plugins include:
| Plugin | Seconds | Remote APIs | Used For
|--------------|---------|----------------|------------------------
| alerts | 5 | -- | Network alert pages
| autocrossref | 90 | -- | Developer documentation
| contributors | 5 | GitHub.com | Contributor listings
| events | 5 | Meetup.com; Google Maps | Events page
| glossary | 30 | -- | Developer glossary
| redirects | 20 | -- | Redirects from old URLs
| releases | 10 | -- | Bitcoin Core release notes; Download page
| sitemap | 10 | -- | /sitemap.xml
Notes: some plugins interact with each other or with translations; for example running
'autocrossref' and 'glossary' takes longer than running each other
separately. Also, plugins that use remote APIs may take a long time to
run if the API site is running slow.
For a list of languages, look in the `_translations` directory.
#### Publishing Previews
You can publish your previews online to any static hosting service.
[GitHub pages](https://pages.github.com/) is a free service available to
all GitHub users that works with Bitcoin.org's site hierarchy.
Before building a preview site, it is recommended that you set the
environmental variable `BITCOINORG_BUILD_TYPE` to "preview". This will
enable some content that would otherwise be hidden and also create a
robots.txt file that will help prevent the site from being indexed by
search engines and mistaken for the actual Bitcoin.org website.
In the bash shell, you can do this by running the following command line
before building you preview:
export BITCOINORG_BUILD_TYPE=preview
You can also add this line to your `~/.bashrc` file if you frequently
build site previews so that you don't have to remember to run it for
each shell.
## Developer Documentation
Most parts of the documentation can be found in the [_includes](https://github.com/bitcoin-dot-org/bitcoin.org/tree/master/_includes)

192
docs/setting-up-your-environment.md Normal file
View file

@ -0,0 +1,192 @@
### Previewing
#### Preview Small Text Changes
Simple text changes can be previewed live on bitcoin.org. You only need to click
anywhere on the page and hold your mouse button for one second. You'll then be
able to edit the page just like a document. Changes will be lost as soon as the
page is refreshed.
#### Build The Site Locally
For anything more than simple text previews, you will need to build the
site. If you can't do this yourself using the instructions below, please
[open a pull request][pull request] with your suggested change and one
of the site developers will create a preview for you.
To build the site, you need to go through a one-time installation
procedure that takes 15 to 30 minutes. After that you can build the
site an unlimited number of times with no extra work.
##### Install The Dependencies
Before building the site, you need to install the following
dependencies and tools, which are pretty easy on any modern Linux:
**Install binary libraries and tools**
On recent versions of Ubuntu and Debian, you can run the following
command to ensure you have the required libraries, headers, and tools:
sudo apt-get install build-essential git libicu-dev zlib1g-dev
**Install RVM**
Install RVM using either the [easy instructions](https://rvm.io/) or the
[more secure instructions](https://rvm.io/rvm/security).
Read the instructions printed to your console during setup to enable the
`rvm` command in your shell. After installation, you need to run the
following command:
source ~/.rvm/scripts/rvm
**Install Ruby 2.0.0**
To install Ruby 2.0.0, simply run this command:
rvm install ruby-2.0.0
Sometimes this will find a pre-compiled Ruby package for your Linux
distribution, but sometimes it will need to compile Ruby from scratch
(which takes about 15 minutes).
After Ruby 2.0.0 is installed, make it your default Ruby:
rvm alias create default ruby-2.0.0
And tell your system to use it:
rvm use default
(Note: you can use a different default Ruby, but if you ever change
your default Ruby, you must re-run the `gem install bundle` command
described below before you can build the site. If you ever receive a
"eval: bundle: not found" error, you failed to re-run `gem install
bundle`.)
**Install Bundle**
When you used RVM to install Ruby, it also installed the `gem` program.
Use that program to install bundle:
gem install bundle
**Install the Ruby dependencies**
Ensure you checked out the site repository as described in [Working with
GitHub](#working-with-github). Then change directory to the top-level of
your local repository (replace `bitcoin.org` with the full path to your local
repository clone):
cd bitcoin.org
And install the necessary dependencies using Bundle:
bundle install
Note that some of the dependencies (particularly nokogiri) can take a
long time to install on some systems, so be patient.
Once Bundle completes successfully, you can preview or build the site.
##### Preview The Site
To preview the website in your local browser, make sure you're in the
`bitcoin.org` directory and run the following command:
make preview
This will compile the site (takes 5 to 10 minutes; see the [speed up
instructions](#fast-partial-previews-or-builds)) and then print the a message
like this:
Server address: http://0.0.0.0:4000
Server running... press ctrl-c to stop.
Visit the indicated URL in your browser to view the site.
##### Build The Site
To build the site exactly like we do for the deployment server, make
sure you're in the `bitcoin.org` directory and run:
make
The resulting HTML for the entire site will be placed in the `_site`
directory. The following alternative options are available:
## After you build the site, you can run all of the tests (may take awhile)
make test
## Or you can build the site and run some quick tests with one command:
make valid
## Or build the site and run all tests
make all
#### Fast Partial Previews Or Builds
In order to preview some changes faster, you can disable all plugins and
languages except those you need by prefixing the `ENABLED_LANGS` and
`ENABLED_PLUGINS` environment variables to your command line. For
example, do this to disable everything:
## Fast preview, takes less than 30 seconds
ENABLED_PLUGINS="" ENABLED_LANGS="" make preview
## Fast build and tests, takes less than 50 seconds
## Some tests may fail in fast mode; use -i to continue despite them
ENABLED_PLUGINS="" ENABLED_LANGS="" make -i valid
Then to enable some plugins or languages, you can add them back in.
For example:
## Slower (but still pretty fast) build and test
ENABLED_PLUGINS="events autocrossref" ENABLED_LANGS="en fr" make -i valid
Plugins include:
| Plugin | Seconds | Remote APIs | Used For
|--------------|---------|----------------|------------------------
| alerts | 5 | -- | Network alert pages
| autocrossref | 90 | -- | Developer documentation
| contributors | 5 | GitHub.com | Contributor listings
| events | 5 | Meetup.com; Google Maps | Events page
| glossary | 30 | -- | Developer glossary
| redirects | 20 | -- | Redirects from old URLs
| releases | 10 | -- | Bitcoin Core release notes; Download
page
| sitemap | 10 | -- | /sitemap.xml
Notes: some plugins interact with each other or with translations; for example
running
'autocrossref' and 'glossary' takes longer than running each other
separately. Also, plugins that use remote APIs may take a long time to
run if the API site is running slow.
For a list of languages, look in the `_translations` directory.
#### Publishing Previews
You can publish your previews online to any static hosting service.
[GitHub pages](https://pages.github.com/) is a free service available to
all GitHub users that works with Bitcoin.org's site hierarchy.
Before building a preview site, it is recommended that you set the
environmental variable `BITCOINORG_BUILD_TYPE` to "preview". This will
enable some content that would otherwise be hidden and also create a
robots.txt file that will help prevent the site from being indexed by
search engines and mistaken for the actual Bitcoin.org website.
In the bash shell, you can do this by running the following command line
before building you preview:
export BITCOINORG_BUILD_TYPE=preview
You can also add this line to your `~/.bashrc` file if you frequently
build site previews so that you don't have to remember to run it for
each shell.
**Questions?**
Contact Will Binns <will@bitcoin.org> for help.