Merge pull request #60 from neptune-ai/update-docs-and-user-facing-co…

…ntent update docs and user facing content
neptune-ai · Jun 20, 2023 · e283173 · e283173
2 parents 5d4c79f + be06ca3
commit e283173
Show file tree

Hide file tree

Showing 8 changed files with 25 additions and 121 deletions.
diff --git a/README.md b/README.md
@@ -1,116 +1,3 @@
-# neptune-tensorboard
+# Neptune-TensorBoard integration
 
-> **Note**
->
-> _This integration is still being updated for the main Neptune client library. It is currently only available for the Neptune legacy API._
-
----
-
-[![PyPI version](https://badge.fury.io/py/neptune-tensorboard.svg)](https://badge.fury.io/py/neptune-tensorboard)
-
-![TensorBoard neptune.ai integration](docs/_static/tensorboard_neptuneml.png)
-
-## Overview
-`neptune-tensorboard` integrates TensorBoard with Neptune to give you the best of both worlds.
-Enjoy tracking from TensorBoard with the organization and collaboration of Neptune.
-
-With `neptune-tensorboard` you can have your TensorBoard experiment runs hosted in a beautiful knowledge repo that lets you invite and manage project contributors.
-
-All you need to do to convert your past runs from TensorBoard logdir is run:
-
-```bash
-neptune tensorboard /path/to/logdir --project USER_NAME/PROJECT_NAME
-```
-
-You can connect Neptune to your TensorBoard and log all future experiments by adding the following to your scripts:
-
-```python
-import neptune
-import neptune_tensorboard as neptune_tb
-
-neptune.init(api_token='YOUR_TOKEN', project_qualified_name='USER_NAME/PROJECT_NAME') # credentials
-neptune_tb.integrate_with_tensorflow()
-
-neptune.create_experiment()
-```
-
-You will have your experiments hosted on Neptune and easily shareable with the world.
-
-## Documentation
-
-See [neptune-tensorboard docs](https://docs-legacy.neptune.ai/integrations/tensorboard.html) for more info.
-
-## Get started
-
-### Register
-Go to [neptune.ai](http://bit.ly/2uUd9AB) and sign up.
-
-It is completely free for individuals and non-organizations, and you can invite others to join your team!
-
-### Get your API token
-
- In the bottom-left corner, click your user menu and select **Get your API token**.
-
-### Set NEPTUNE_API_TOKEN environment variable
-
-Go to your console and run:
-
-```
-export NEPTUNE_API_TOKEN='your_long_api_token'
-```
-
-### Create your first project
-
-Click **All projects** &rarr; **New project**. Choose a name for it and whether you want it public or private.
-
-### Install lib
-
-```bash
-pip install neptune-tensorboard
-```
-
-### Sync your TensorBoard logdir with Neptune
-
-```bash
-neptune tensorboard /path/to/logdir --project USER_NAME/PROJECT_NAME
-```
-
-### Connect Neptune to TensorBoard to log future runs
-
-You can connect Neptune to your TensorBoard and log all future experiments by adding the following to your scripts:
-
-```python
-import neptune
-import neptune_tensorboard as neptune_tb
-
-neptune.init(api_token='YOUR_TOKEN', project_qualified_name='USER_NAME/PROJECT_NAME')  # credentials
-neptune_tb.integrate_with_tensorflow()
-
-neptune.create_experiment()
-```
-
-### Explore and Share
-
-You can now explore and organize your experiments in Neptune, and share it with anyone:
-
-* by sending a link to your project, experiment or chart if it is public
-* or invite people to your project if you want to keep it private!
-
-## Getting help
-
-If you get stuck, don't worry. We are here to help.
-
-The best order of communication is:
-
- * [GitHub issues](https://github.com/neptune-ai/neptune-tensorboard/issues)
- * [Email](mailto:support@neptune.ai)
-
-## Contributing
-
-If you see something that you don't like, you are more than welcome to contribute!
-
-There are many options:
-
-* Submit a feature request or a bug here, on Github
-* Submit a pull request that deals with an open feature request or bug
-* Spread the word about Neptune in your community
+See [the official docs](https://docs.neptune.ai/integrations/tensorboard/).
diff --git a/src/neptune_tensorboard/integration/__init__.py b/src/neptune_tensorboard/integration/__init__.py
@@ -55,9 +55,10 @@ def check_tf_version():
             if version >= parse_version(MIN_TF_VERSION):
                 return
         except AttributeError:
+            # user facing
             message = (
-                f"Unrecognized tensorflow version: {version}. Please make sure "
-                "that the tensorflow version is >={MIN_TF_VERSION}"
+                f"Unrecognized TensorFlow version: {version}. Please make sure "
+                "that the TensorFlow version is >={MIN_TF_VERSION}"
             )
             raise Exception(message)
 
@@ -80,6 +81,7 @@ def check_pytorch_version():
             if version >= parse_version(MIN_PT_VERSION):
                 return
         except AttributeError:
+            # user facing
             message = (
                 f"Unrecognized PyTorch version: {version}. Please make sure "
                 "that the PyTorch version is >={MIN_PT_VERSION}"
@@ -105,15 +107,17 @@ def check_tensorboardx_version():
             if version >= parse_version(MIN_TBX_VERSION):
                 return
         except AttributeError:
+            # user facing
             message = (
                 f"Unrecognized tensorboardX version: {version}. Please make sure "
                 "that the tensorboardX version is >={MIN_TBX_VERSION}"
             )
             raise Exception(message)
 
 
+# user facing
 FRAMEWORK_NOT_FOUND_WARNING_MSG = (
-    "neptune-tensorboard: Tensorflow or PyTorch or tensorboardX was not found, ",
+    "neptune-tensorboard: TensorFlow or PyTorch or tensorboardX was not found, ",
     "please ensure that it is available.",
 )
 

diff --git a/src/neptune_tensorboard/integration/pytorch_integration.py b/src/neptune_tensorboard/integration/pytorch_integration.py
@@ -73,6 +73,7 @@ def track_images(
     elif dataformats == "NHWC":
         pass
     else:
+        # user facing
         warnings.warn("neptune-tensorboard: Skipping logging images as  {dataformats} is not supported.")
 
     for idx in range(img_tensor.shape[0]):
@@ -93,10 +94,12 @@ def track_graph(
     summary_writer, model, input_to_model=None, verbose=False, use_strict_trace=True, run=None, base_namespace=None
 ):
     if not IS_TORCHVIZ_AVAILABLE:
+        # user facing
         msg = "neptune-tensorboard: Skipping model visualization because no torchviz installation was found."
         warnings.warn(msg)
         return
     if input_to_model is None:
+        # user facing
         msg = "neptune-tensorboard: Skipping model visualization because input_to_model was None."
         warnings.warn(msg)
         return

diff --git a/src/neptune_tensorboard/integration/tensorboardx_integration.py b/src/neptune_tensorboard/integration/tensorboardx_integration.py
@@ -73,6 +73,7 @@ def track_images(
     elif dataformats == "NHWC":
         pass
     else:
+        # user facing
         warnings.warn("neptune-tensorboard: Skipping logging images as  {dataformats} is not supported.")
 
     for idx in range(img_tensor.shape[0]):
@@ -93,10 +94,12 @@ def track_graph(
     summary_writer, model, input_to_model=None, verbose=False, use_strict_trace=True, run=None, base_namespace=None
 ):
     if not IS_TORCHVIZ_AVAILABLE:
+        # user facing
         msg = "neptune-tensorboard: Skipping model visualization because no torchviz installation was found."
         warnings.warn(msg)
         return
     if input_to_model is None:
+        # user facing
         msg = "neptune-tensorboard: Skipping model visualization because input_to_model was None."
         warnings.warn(msg)
         return

diff --git a/src/neptune_tensorboard/integration/tensorflow_integration.py b/src/neptune_tensorboard/integration/tensorflow_integration.py
@@ -66,7 +66,8 @@ def track_graph(graph_data, run=None, base_namespace=None):
         # There is only one graph
         run[base_namespace]["graph"].upload(File.from_content(png_bytes, extension="png"))
     else:
-        warnings.warn("Skipping model visualization because no tfgraphviz installation was found.")
+        # user facing
+        warnings.warn("neptune-tensorboard: Skipping model visualization because no tfgraphviz installation was found.")
 
 
 class NeptuneTensorflowTracker(contextlib.AbstractContextManager):

diff --git a/src/neptune_tensorboard/integration/version.py b/src/neptune_tensorboard/integration/version.py
@@ -15,6 +15,7 @@
     )
 
 if not (find_spec("neptune") or find_spec("neptune-client")):
+    # user facing
     msg = """
             The Neptune client library was not found.
 

diff --git a/src/neptune_tensorboard/sync/sync_impl.py b/src/neptune_tensorboard/sync/sync_impl.py
@@ -9,7 +9,8 @@
 try:
     import tbparse
 except ModuleNotFoundError:
-    raise ModuleNotFoundError("neptune-tensorboard: require `tbparse` for exporting logs (pip install tbparse)")
+    # user facing
+    raise ModuleNotFoundError("neptune-tensorboard: tbparse is required for exporting logs. Install it with: pip install tbparse")
 
 
 def compute_md5_hash(path):
@@ -37,6 +38,7 @@ def run(self):
                 if self._is_valid_tf_event_file(str_path):
                     self._export_to_neptune_run(str_path)
             except Exception as e:
+                # user facing
                 click.echo("Cannot load run from file '{}'. ".format(path) + "Error: " + str(e))
                 try:
                     traceback.print_exc(e)
@@ -68,7 +70,8 @@ def _export_to_neptune_run(self, path):
         hash_run_id = compute_md5_hash(path)
 
         if self._experiment_exists(hash_run_id, self._project):
-            click.echo(f"{path} was already synced")
+            # user facing
+            click.echo(f"{path} was already synchronized")
             return
 
         with neptune.init_run(custom_run_id=hash_run_id, project=self._project, api_token=self._api_token) as run:
@@ -95,4 +98,5 @@ def _export_to_neptune_run(self, path):
             for hparam in reader.hparams.itertuples():
                 namespace_handler["hparams"][hparam.tag].append(hparam.value)
 
+            # user facing
             click.echo(f"{path} was exported with run_id: {hash_run_id}")
diff --git a/src/neptune_tensorboard_plugin/__init__.py b/src/neptune_tensorboard_plugin/__init__.py
@@ -9,6 +9,7 @@
 @click.argument("log_dir", required=True)
 def sync(project, api_token, log_dir):
     if not os.path.exists(log_dir):
+        # user facing
         click.echo("ERROR: Provided `log_dir` path doesn't exist", err=True)
         return