Manage the Epsilon web site locally¶
This article provides a step-by-step guide for obtaining a local copy of the Epsilon website. The website is managed using the mkdocs library. The content is organised in different Markdown files, from which a static website can be generated.
Setting up your environment¶
- Clone the Git repository at
ssh://email@example.com:29418/www.eclipse.org/epsilon.gitif you are a project comitter, or at
- Download and install virtualenv.
- Navigate to the
mkdocsfolder, and run
./serve.shfrom a terminal. The first time this command is run, a Python virtual environment will be created unther the
mkdocs/envdirectory. After the environment is ready (and on subsequent calls to
./serve.sh), a local web server containing the Epsilon website will be running at http://localhost:8000.
Real-time modification of the website¶
All the Markdown sources of the website are contained in the
mkdocs folder. After running the
./serve.sh command, we can alter these sources, and the changes will be reflected automatically in the local website. This is very useful to get quick feedback of our changes, as we do not have to regenerate the website each time we make a modification.
To shutdown the local web server at any time, hit
CTRL + C on the terminal you used to launch it in the first place.
Building the static site¶
Once you've happy with the changes you've made to the Markdown sources, you can re-generate the static website. To do so, run
./build.sh and wait for it to finish.
Updating the website contents¶
As a convention for project commiters, introducing a change in the website is usually separated in two commits: the first one contains any changes to the Markdown sources, while the second one includes the result of building again the static site as described in the previous section.
If you are not a commiter, but you find any typos or parts of the website that do not work as they should, thanks for letting us know!
Pushing your changes¶
When pushing your changes, please make sure to add the
-s flag to your commit command (e.g.
git commit -m "Added new article" -s), to add a sign-off footer, which is required by Gerrit since mid-December 2020. There is also a
publish.sh script in the repo, which creates separate commits for the changes to
mkdocs and the changes to the generated static files, and then pushes both commits to the remote repo. You can use it as follows:
./publish.sh "Added new article".
Finding broken links¶
grep can be used to find broken links in the Epsilon website. First, run the website locally by executing the
./serve.sh command as described above. Then, we will traverse the website using
wget with this command:
wget -e robots=off --spider -r --no-parent -o wget_errors.txt http://localhost:8000
We have used these options:
robots.txt. This is OK in this case, as we're running the spider on our own local server.
wgetfrom downloading page requisites that do not contain links
wgettraverse through links
-o wget_errors.txtcollects all messages in the
Once it's done, we can simply search for the word "404" in the log, with:
grep -B2 -w 404 wget_errors.txt
We will get a list of all the URLs which reported 404 (Not Found) HTTP error codes.