perfSONAR Documentation

This repository contains installation and configuration documentation related to the perfSONAR project. The master branch contains the raw files for the documents hosted at http://docs.perfsonar.net. See the remainder of the README for more information on editing and deploying the perfSONAR documentation.

Documentation Format

The perfSONAR documentation is generated by Sphinx and uses the reStructuredText format. See those sites for details.

Preparing Your Environment

You will need to build the files using the Sphinx Python Library. You can do this directly on your system or use the proviided docker container.

You can start the container as follows:

cp env.example .env 
docker-compose up -d

Fill-in any git credentials in .env if you plan to use deploy scripts. Any of the commands in the remainder of this document can be executed with docker-compose exec docs_build COMMAND and will run inside container.

Alternatively, for direct install on most systems this means running the following:

pip install sphinx

See http://sphinx-doc.org/install.html for operating system specific instructions.

Previewing the site

From the top-level directory of this repository run:

make html

This will generate a set of HTML files that can be opened in your browser under _build/html/. You can view the main page by opening _build/html/index.html in your browser.

Deploying Documentation to docs.perfsonar.net

Simply push your changes to the master branch and the documentation will be published within 15 minutes to http://docs.perfsonar.net. This is handled by a script running on the hosting server that polls the git repository every 15 minutes and rebuilds the site if changes are detected. If you can't wait that long, run make html followed by deploy.sh to deploy your changes.

Deploying a release candidate

A script is provided to deploy documentation for a release candidate. The basic process is that the documentation for the release candidate is done in a branch and then we push out the branch using a shell script.

Once your branch is ready simply run the deploy_release_candidate.sh script to publish the branch (substituting BRANCH with the BRANCH name):

./deploy_release_candidate.sh BRANCH

This will create a new directory with the docs at http://docs.perfsonar.net/release_candidates/BRANCH. If you need to update existing docs, simply run the script again to push out changes.

Deploying a previous release

A script is provided to deploy documentation for previous releases. The basic process is that the documentation for the previous release must be tagged on master where the version number is the tag. This will in turn create a link under /previous_releases/VERSION with the old version of the documentation.

Following the process above, the first step is to create the tag, where TAG is the version number (e.g. 3.4.2) and COMMIT is the commit hash (e.g. 4305a6e72c0df0b929412fea19f7402f74b1ab8f):

git tag TAG COMMIT

Next we simply run the deploy_prev_release.sh script to publish the tag (again substituting TAG with the version number):

./deploy_prev_release.sh TAG

Finally, you will want to add a link to previous_releases.rst and publish by hand when you are ready to share.

Name		Name	Last commit message	Last commit date
Latest commit History 985 Commits
_static		_static
_templates		_templates
images		images
psconfig_templates		psconfig_templates
.gitignore		.gitignore
Dockerfile		Dockerfile
FAQ.rst		FAQ.rst
Makefile		Makefile
README.md		README.md
client_apis.rst		client_apis.rst
client_tools.rst		client_tools.rst
conf.py		conf.py
config_files.rst		config_files.rst
config_ls_registration.rst		config_ls_registration.rst
config_owamp.rst		config_owamp.rst
config_owamp_limits.rst		config_owamp_limits.rst
config_pscheduler.rst		config_pscheduler.rst
config_pscheduler_limits.rst		config_pscheduler_limits.rst
create_rst.sh		create_rst.sh
deploy.sh		deploy.sh
deploy_prev_release.sh		deploy_prev_release.sh
deploy_release_candidate.sh		deploy_release_candidate.sh
deployment_examples.rst		deployment_examples.rst
docker-compose.yml		docker-compose.yml
env.example		env.example
esmond_api_perl.rst		esmond_api_perl.rst
esmond_api_python.rst		esmond_api_python.rst
esmond_api_rest.rst		esmond_api_rest.rst
grafana_cookbook.rst		grafana_cookbook.rst
index.rst		index.rst
install_ansible.rst		install_ansible.rst
install_centos.rst		install_centos.rst
install_config_first_time.rst		install_config_first_time.rst
install_debian.rst		install_debian.rst
install_docker.rst		install_docker.rst
install_getting.rst		install_getting.rst
install_hardware.rst		install_hardware.rst
install_hardware_details.rst		install_hardware_details.rst
install_options.rst		install_options.rst
install_quick_start.rst		install_quick_start.rst
install_rcs.rst		install_rcs.rst
install_small_node_details.rst		install_small_node_details.rst
install_virtual_machine_details.rst		install_virtual_machine_details.rst
intro_about.rst		intro_about.rst
legacy_archive_esmond.rst		legacy_archive_esmond.rst
maddash_admin_ui.rst		maddash_admin_ui.rst
maddash_api_cells.rst		maddash_api_cells.rst
maddash_api_checks.rst		maddash_api_checks.rst
maddash_api_dashboards.rst		maddash_api_dashboards.rst
maddash_api_events.rst		maddash_api_events.rst
maddash_api_grids.rst		maddash_api_grids.rst
maddash_api_intro.rst		maddash_api_intro.rst
maddash_api_misc.rst		maddash_api_misc.rst
maddash_api_reports.rst		maddash_api_reports.rst
maddash_api_rows.rst		maddash_api_rows.rst
maddash_api_type_params.rst		maddash_api_type_params.rst
maddash_config_server.rst		maddash_config_server.rst
maddash_config_webui.rst		maddash_config_webui.rst
maddash_install.rst		maddash_install.rst
maddash_intro.rst		maddash_intro.rst
maddash_running.rst		maddash_running.rst
manage_admin_info.rst		manage_admin_info.rst
manage_choose.rst		manage_choose.rst
manage_daemons.rst		manage_daemons.rst
manage_dual_xface.rst		manage_dual_xface.rst
manage_limits.rst		manage_limits.rst
manage_locating_hosts.rst		manage_locating_hosts.rst
manage_logs.rst		manage_logs.rst
manage_ntp.rst		manage_ntp.rst
manage_regular_tests.rst		manage_regular_tests.rst
manage_security.rst		manage_security.rst
manage_tuning.rst		manage_tuning.rst
manage_update.rst		manage_update.rst
manage_users.rst		manage_users.rst
multi_ma_install.rst		multi_ma_install.rst
ntp_overview.rst		ntp_overview.rst
previous_releases.rst		previous_releases.rst
pscheduler_batch.rst		pscheduler_batch.rst
pscheduler_client_schedule.rst		pscheduler_client_schedule.rst
pscheduler_client_tasks.rst		pscheduler_client_tasks.rst
pscheduler_disk_to_disk.rst		pscheduler_disk_to_disk.rst
pscheduler_intro.rst		pscheduler_intro.rst
pscheduler_ref_archivers.rst		pscheduler_ref_archivers.rst
pscheduler_ref_bwctl.rst		pscheduler_ref_bwctl.rst
pscheduler_ref_contexts.rst		pscheduler_ref_contexts.rst
pscheduler_ref_tests_tools.rst		pscheduler_ref_tests_tools.rst
pscheduler_server_running.rst		pscheduler_server_running.rst
psconfig_intro.rst		psconfig_intro.rst
psconfig_maddash_agent.rst		psconfig_maddash_agent.rst
psconfig_pscheduler_agent.rst		psconfig_pscheduler_agent.rst
psconfig_publish.rst		psconfig_publish.rst
psconfig_quickstart.rst		psconfig_quickstart.rst
psconfig_templates_advanced.rst		psconfig_templates_advanced.rst
psconfig_templates_intro.rst		psconfig_templates_intro.rst
psconfig_templates_vars.rst		psconfig_templates_vars.rst
pwa.rst		pwa.rst
pwa_api.rst		pwa_api.rst
pwa_configure.rst		pwa_configure.rst
pwa_docker_architecture.rst		pwa_docker_architecture.rst
pwa_docker_create.rst		pwa_docker_create.rst

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

perfSONAR Documentation

Documentation Format

Preparing Your Environment

Previewing the site

Deploying Documentation to docs.perfsonar.net

Deploying a release candidate

Deploying a previous release

About

Releases

Packages

Languages

znewell-nshe/docs

Folders and files

Latest commit

History

Repository files navigation

perfSONAR Documentation

Documentation Format

Preparing Your Environment

Previewing the site

Deploying Documentation to docs.perfsonar.net

Deploying a release candidate

Deploying a previous release

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages