Merge pull request #113 from SNEWS2/improve_docs

Improve docs
SNEWS2 · Aug 13, 2024 · 62a6252 · 62a6252
2 parents adbea15 + af54c42
commit 62a6252
Show file tree

Hide file tree

Showing 26 changed files with 166 additions and 425 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,11 @@
 # SNEWS Publishing Tool
-<img src="docs/custom_logo.png" alt="snews_logo" width="200"/> 
+<img src="docs/_static/images/custom_logo.png" alt="snews_logo" width="200"/> 
 
 [![Documentation Status](https://readthedocs.org/projects/snews-publishing-tools/badge/?version=latest)](https://snews-publishing-tools.readthedocs.io/en/latest/?badge=latest)
 [![PyPI](https://img.shields.io/pypi/v/snews_pt)](https://pypi.org/project/snews_pt/)
 ![testing](https://github.com/SNEWS2/SNEWS_Publishing_Tools/actions/workflows/ubuntu22-py311-312.yml/badge.svg)
+[![arXiv](https://img.shields.io/badge/arXiv-1234.56789-b31b1b.svg)](https://arxiv.org/abs/2406.17743)
+
 <br>See the docs at
 
 |              |        |

diff --git a/docs/README.md b/docs/README.md
@@ -1,5 +1,10 @@
-# SNEWS Publishing Tool Documentation
+# SNEWS Publishing Tools Documentation
 
-See [main readme](../README.md) for installation and API guide. <br>
-See [this documentation](cli_docs.md) for a tutorial of command line interface (CLI) tools.
+See the documentation at [snews-publishing-tools.readthedocs.io](https://snews-publishing-tools.readthedocs.io/en/latest/)
+
+[![PyPI](https://img.shields.io/pypi/v/snews_pt)](https://pypi.org/project/snews_pt/)
+[![Documentation Status](https://readthedocs.org/projects/snews-publishing-tools/badge/?version=latest)](https://snews-publishing-tools.readthedocs.io/en/latest/?badge=latest)
+
+[//]: # (See [main readme]&#40;../README.md&#41; for installation and API guide. <br>)
+[//]: # (See [this documentation]&#40;cli_docs.md&#41; for a tutorial of command line interface &#40;CLI&#41; tools.)
 
diff --git a/docs/_static/css/my_theme.css b/docs/_static/css/my_theme.css
@@ -20,7 +20,7 @@
 .wy-nav-top {
 	background-color: #3B556F;
 	#background-color: #fcfcfc;
-	background-image: url('../logo.png');
+	background-image: url('../images/custom_logo.png');
 	background-repeat: no-repeat;
 	background-position: bottom;
 	padding: 0;

diff --git a/docs/custom_logo.png → docs/_static/images/custom_logo.png b/docs/custom_logo.png → docs/_static/images/custom_logo.png
diff --git a/docs/required_permissions.png → docs/_static/images/required_permissions.png b/docs/required_permissions.png → docs/_static/images/required_permissions.png
diff --git a/docs/test-connection-screenshot.png → ...tic/images/test-connection-screenshot.png b/docs/test-connection-screenshot.png → ...tic/images/test-connection-screenshot.png
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -1,2 +1,2 @@
-{%- set logo = "logo.png" %}
+{%- set logo = "../_static/images/custom_logo.png" %}
 {% extends "!layout.html" %}
diff --git a/docs/api/api.rst b/docs/api/api.rst
diff --git a/docs/api/message_schema.rst b/docs/api/message_schema.rst
diff --git a/docs/api/snews_pt_utils.rst b/docs/api/snews_pt_utils.rst
diff --git a/docs/api/snews_pub.rst b/docs/api/snews_pub.rst
diff --git a/docs/api/snews_sub.rst b/docs/api/snews_sub.rst
diff --git a/docs/cli_docs.md b/docs/cli_docs.md
diff --git a/docs/cli_help.txt b/docs/cli_help.txt
diff --git a/docs/conf.py b/docs/conf.py
@@ -114,7 +114,7 @@ def setup(app):
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
-html_logo = "./custom_logo.png"
+html_logo = "./_static/images/custom_logo.png"
 html_theme_options = {
     'logo_only': True,
     'display_version': True,

diff --git a/docs/example_publishing.png b/docs/example_publishing.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -10,11 +10,13 @@ User's Guide
    index
    user/installation
    user/quickstart
+   user/hopskotch
    user/publishing_protocols
    user/subscribing
    user/remote_commands
    user/command_line_interface
    user/firedrills
+   user/faq
 
 
 API Reference

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,24 +1,4 @@
-# Required packages
-#
-click~=8.1
-hop-client~=0.8.0
-inquirer~=2.8
-ipython~=8.7
-numpy~=1.26
-python-dotenv~=0.19
-setuptools~=69.0
-wheel~=0.42
-#
-# Development packages
-#
-virtualenv~=20.13
-pytest~=8.0
-pytest-console-scripts~=1.4
-pytest-cov~=4.1
-pytest-mongodb~=2.4
-pytest-runner~=6.0
-#
-# Documentation packages 
+# Documentation packages
 #
 autoapi~=2.0.1
 myst-parser~=2.0

diff --git a/docs/snews_logo.png b/docs/snews_logo.png
diff --git a/docs/subscribed_messages.json b/docs/subscribed_messages.json
diff --git a/docs/user/faq.md b/docs/user/faq.md
@@ -0,0 +1,35 @@
+
+# FAQ and Troubleshooting
+
+We try to collect the common questions and issues that users have when using the SNEWS Publishing Tool. 
+If you have a question that is not answered here, please feel free to open an issue on the [GitHub repository](https://github.com/SNEWS2/SNEWS_Publishing_Tools)
+
+## How do I set up my hop credentials?
+
+Easiest is to follow the instructions in the [Quick Start](https://snews-publishing-tools.readthedocs.io/en/latest/user/quickstart.html) guide. <br>
+Once created you can add your credentials from the terminal
+
+```bash
+hop auth add
+```
+which will prompt you to enter your username and password. Then your credentials will be stored on your local machine (`hop auth locate`).
+You do not need to do anything else, as snews_pt will automatically use these credentials when you publish or subscribe to the SNEWS servers.
+
+## How do I know if I have the correct permissions to publish or subscribe to the SNEWS servers?
+During development and in the actual production environment, you will need to have the correct permissions to publish or subscribe to the SNEWS servers.
+The permissions are given for certain topics within certain groups. Simply go to [https://my.hop.scimma.org/hopauth/](https://my.hop.scimma.org/hopauth/) and check if you are in snews group.
+If so, check which topics you have access to. The topics are explained in [hopskotch page](./hopskotch.md). If you are not in the snews user groups, request to be added by sending a message on SNEWS slack, on the implementation channel.
+
+## Kafka Errors
+There can be many reasons for Kafka errors. The most common ones are;
+ ### Network is unreachable
+If your network is not reachable, you will get an error message like this;
+```bash
+%3|1723572803.484|FAIL|rdkafka#consumer-2| [thrd:sasl_ssl://kafka.scimma.org:9092/bootstrap]: sasl_ssl://kafka.scimma.org:9092/bootstrap: Failed to connect to broker at [ns-137.awsdns-17.com]:9092: Network is unreachable (after 20ms in state CONNECT)
+...
+cimpl.KafkaException: KafkaError{code=_TRANSPORT,val=-195,str="Failed to get metadata: Local: Broker transport failure"}
+```
+Try using a different network to confirm if the issue is with your network. Sometimes, the network you are using might have a firewall that blocks the connection to the Kafka server.
+
+
+
diff --git a/docs/user/installation.md b/docs/user/installation.md
@@ -1,3 +1,8 @@
+[![Documentation Status](https://readthedocs.org/projects/snews-publishing-tools/badge/?version=latest)](https://snews-publishing-tools.readthedocs.io/en/latest/?badge=latest)
+[![PyPI](https://img.shields.io/pypi/v/snews_pt)](https://pypi.org/project/snews_pt/)
+![testing](https://github.com/SNEWS2/SNEWS_Publishing_Tools/actions/workflows/ubuntu22-py311-312.yml/badge.svg)
+[![arXiv](https://img.shields.io/badge/arXiv-1234.56789-b31b1b.svg)](https://arxiv.org/abs/2406.17743)
+
 # Installation
 
 You can install SNEWS publishing tools (snews_pt) from [PyPi](https://pypi.org/project/snews-pt/) via pip,