Feature/dev 872 Refactored Docs to scaladoc (#388)

* up to row
remove do not document

* remove annoying {s}

* check in before home time, done apis, skipped algos on query

* refractor doc

* client and sender done

* anything that had a doc in core has been converted

* put back {s} into algorithms

* addded build sbt support and move files, but where are my files going? why sphinx not liking the same names... urg

* linked scala doc but need to fix references

* fix scaladoc role for linking to documentation

* add {scaladoc} rule to docs

* fixed python client

* fix links to methods

* fixed some warnings and headers

* forgot to do graph algorithm

* added environment

Co-authored-by: Lucas Jeub <[email protected]>

Author: Haaroon

.environment.yml

@@ -0,0 +1,57 @@
+name: py39
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - ca-certificates=2021.10.8=h033912b_0
+  - certifi=2021.10.8=py39h6e9494a_2
+  - libcxx=12.0.0=h2f01273_0
+  - libffi=3.3=hb1e8313_2
+  - ncurses=6.3=hca72f7f_2
+  - openjdk=11.0.9.1=hcf210ce_1
+  - openssl=1.1.1o=hfe4f2af_0
+  - pip=21.2.4=py39hecd8cb5_0
+  - python=3.9.12=hdfd78df_0
+  - python_abi=3.9=2_cp39
+  - readline=8.1.2=hca72f7f_1
+  - sbt=1.6.2=hd8ed1ab_0
+  - setuptools=61.2.0=py39hecd8cb5_0
+  - sqlite=3.38.3=h707629a_0
+  - tk=8.6.11=h3fd3227_1
+  - tzdata=2022a=hda174b7_0
+  - wheel=0.37.1=pyhd3eb1b0_0
+  - xz=5.2.5=hca72f7f_1
+  - zlib=1.2.12=h4dc903c_2
+  - pip:
+    - alabaster==0.7.12
+    - babel==2.10.1
+    - charset-normalizer==2.0.12
+    - docutils==0.17.1
+    - idna==3.3
+    - imagesize==1.3.0
+    - importlib-metadata==4.11.3
+    - jinja2==3.1.2
+    - markdown-it-py==2.1.0
+    - markupsafe==2.1.1
+    - mdit-py-plugins==0.3.0
+    - mdurl==0.1.1
+    - myst-parser==0.17.2
+    - packaging==21.3
+    - pygments==2.12.0
+    - pyparsing==3.0.8
+    - pytz==2022.1
+    - pyyaml==6.0
+    - requests==2.27.1
+    - snowballstemmer==2.2.0
+    - sphinx==4.5.0
+    - sphinx-rtd-theme==1.0.0
+    - sphinxcontrib-applehelp==1.0.2
+    - sphinxcontrib-devhelp==1.0.2
+    - sphinxcontrib-htmlhelp==2.0.0
+    - sphinxcontrib-jsmath==1.0.1
+    - sphinxcontrib-qthelp==1.0.3
+    - sphinxcontrib-serializinghtml==1.1.5
+    - typing-extensions==4.2.0
+    - urllib3==1.26.9
+    - zipp==3.8.0
+prefix: /Users/haaroony/opt/anaconda3/envs/py39

.readthedocs.yaml

@@ -11,11 +11,10 @@ build:
   tools:
     python: "3.9"
 
+conda:
+  environment: .environment.yml
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/source/conf.py
 
-# Optionally declare the Python requirements required to build your docs
-python:
-   install:
-   - requirements: docs/requirements.txt

build.sbt

@@ -62,6 +62,7 @@ lazy val core = (project in file("core"))
   .settings(
           name := "core",
           assembly / test := {},
+          Compile / doc / scalacOptions := Seq("-skip-packages", "com.raphtory.algorithms.generic:com.raphtory.algorithms.temporal", "-private"),
           assemblySettings,
           defaultSettings,
           libraryDependencies ++= Seq(
@@ -171,3 +172,6 @@ Test / parallelExecution := false
 Global / concurrentRestrictions := Seq(
         Tags.limit(Tags.Test, 1)
 )
+
+// Scaladocs parameters
+// doc / scalacOptions ++= Seq("-skip-packages", "com.raphtory.algorithms.generic:com.raphtory.algorithms.temporal", "-private")

core/src/main/scala/com/raphtory/algorithms/api/Accumulator.scala

@@ -1,23 +1,12 @@
 package com.raphtory.algorithms.api
 
-/**
-  *  {s}`Accumulator[T]`
-  *    : Public accumulator interface
-  *
-  *  ## Methods
-  *
-  *    {s}`+= (newValue: T): Unit`
-  *      : add new value to accumulator
-  *
-  *    {s}`value: T`
-  *      : get last accumulated value
-  *
-  * ```{seealso}
-  * [](com.raphtory.algorithms.api.GraphState)
-  * ```
-  */
+/** Abstract class for the Accumulator interface.
+  * See also com.raphtory.algorithms.api.GraphState */
 abstract class Accumulator[T] {
+
+  /** Add new value to accumulator */
   def value: T
 
+  /** Get last accumulated value */
   def +=(newValue: T): Unit
 }

core/src/main/scala/com/raphtory/algorithms/api/Chain.scala

@@ -1,39 +1,23 @@
 package com.raphtory.algorithms.api
 
-/**
-  * {s}`Chain(algorithms: GraphAlgorithm*)`
-  *  : Run algorithms in sequence with shared graph state
+/** Run algorithms in sequence with shared graph state,
   *
-  * ## Parameters
+  * @see
+  *   [[com.raphtory.algorithms.api.GraphAlgorithm]],
+  *   [[com.raphtory.algorithms.api.GraphPerspective]],
+  *   [[com.raphtory.algorithms.api.Table]]
   *
-  *  {s}`algorithms: GraphAlgorithm*`
-  *    : List of algorithms to run
-  *
-  * ## Class Signature
-  *
-  *  {s}`Chain(algorithms: Seq[GraphAlgorithm]) extends GraphAlgorithm`
-  *
-  * ## Methods
-  *
-  *  {s}`apply(graph: GraphPerspective): GraphPerspective`
-  *    : Apply each algorithm to the graph in sequence, clearing messages in-between.
-  *      This means that while the next algorithm has access to all the graph state set by previous algorithms,
-  *      it does not receive messages sent by the previous algorithm.
-  *
-  *  {s}`tabularise(graph: GraphPerspective): Table`
-  *    : Uses the `tabularise` method of the last algorithm in the chain to return results (if {s}`algorithms`
-  *       is empty, it returns an empty table).
-  *
-  *  {s}`->(graphAlgorithm: GraphAlgorithm): Chain`
-  *    : Append a new graph algorithm to the chain.
-  *
-  *  ```{seealso}
-  *  [](com.raphtory.algorithms.api.GraphAlgorithm), [](com.raphtory.algorithms.api.GraphPerspective),
-  *  [](com.raphtory.algorithms.api.Table)
-  *  ```
-  */
+  * @param algorithms Sequence of GraphAlgorithm(s) to run
+  * */
 class Chain(algorithms: Seq[GraphAlgorithm]) extends GraphAlgorithm {
 
+  /**  Apply each algorithm to the graph in sequence, clearing messages in-between.
+    *  This means that while the next algorithm has access to all the graph state set by previous algorithms,
+    *  it does not receive messages sent by the previous algorithm.
+    *
+    * @param graph The graph perspective to apply the algorithm to
+    * @return a new GraphPerspective that has been modified with the algorithm
+    * */
   override def apply(graph: GraphPerspective): GraphPerspective = {
     var gp = graph
     if (algorithms.nonEmpty)
@@ -42,16 +26,36 @@ class Chain(algorithms: Seq[GraphAlgorithm]) extends GraphAlgorithm {
     gp
   }
 
+  /**  Uses the `tabularise` method of the last algorithm in the chain to return results (if algorithms
+    *  is empty, it returns an empty table).
+    *
+    *  @param graph The graph perspective to apply the algorithm to
+    *  @return Returns a Table with the results, if empty returns an empty table
+    */
   override def tabularise(graph: GraphPerspective): Table =
     if (algorithms.nonEmpty)
       algorithms.last.tabularise(graph)
     else
       super.tabularise(graph)
 
+  /**  Append a new graph algorithm to the chain.
+    *
+    * @param graphAlgorithm the graph algorithm to apply to the chain
+    * @return The chain with the added algorithm
+    */
   override def ->(graphAlgorithm: GraphAlgorithm): Chain =
     Chain(algorithms :+ graphAlgorithm: _*)
 }
 
+/** Factory for [[com.raphtory.algorithms.api.Chain]] objects */
 object Chain {
+
+  /**  Apply each algorithm to the chain in sequence, clearing messages in-between.
+    *  This means that while the next algorithm has access to all the graph state set by previous algorithms,
+    *  it does not receive messages sent by the previous algorithm.
+    *
+    * @param algorithms The graph algorithms to apply
+    * @return a new Chain that has been modified with the algorithms
+    * */
   def apply(algorithms: GraphAlgorithm*) = new Chain(algorithms)
 }

core/src/main/scala/com/raphtory/algorithms/api/DefaultGraphOperations.scala

@@ -7,7 +7,7 @@ import com.raphtory.graph.visitor.PropertyMergeStrategy.PropertyMerge
 import com.raphtory.graph.visitor.Vertex
 
 /**
-  * @DoNotDocument
+  * @note DoNotDocument
   */
 abstract class DefaultGraphOperations[G <: GraphOperations[G]](
     private[api] val query: Query,

core/src/main/scala/com/raphtory/algorithms/api/DeployedTemporalGraph.scala

@@ -4,21 +4,12 @@ import com.raphtory.client.QuerySender
 import com.raphtory.components.querymanager.Query
 import com.typesafe.config.Config
 
-/**
-  * {s}`DeployedTemporalGraph`
-  *  : Root class for local deployments of the analysis API
+/** Root class for local deployments of the analysis API
   *
-  * A {s}`DeployedTemporalGraph` is a {s}`TemporalGraph`
+  * A DeployedTemporalGraph is a TemporalGraph
   * with a deployment object attached to it that allows to stop it.
   *
-  * ## Methods
-  *
-  *  {s}`deployment: Deployment`
-  *    : Access to the deployment to allow stopping it: {s}`graph.deployment.stop()`.
-  *
-  * ```{seealso}
-  * [](com.raphtory.algorithms.api.TemporalGraph)
-  * ```
+  * @see [[com.raphtory.algorithms.api.TemporalGraph]]
   */
 private[raphtory] class DeployedTemporalGraph(
     query: Query,
@@ -32,6 +23,10 @@ private[raphtory] class DeployedTemporalGraph(
   }
   private val deploymentRef = new Deployment()
 
+  /** Access to the deployment to call functions upon it, e.g. graph.deployment.stop()
+    *
+    * @return Deployment reference
+    * */
   def deployment: Deployment = deploymentRef
 
   private[raphtory] def getConfig() = conf