Merge pull request #594 from conjure-cp/docbits

Adding the "bits" in the documentation to sphinx
conjure-cp · Oct 24, 2023 · e1e1625 · e1e1625
2 parents f6adf91 + e0aeb58
commit e1e1625
Show file tree

Hide file tree

Showing 18 changed files with 64 additions and 19 deletions.
diff --git a/.gitignore b/.gitignore
@@ -36,6 +36,7 @@ docs/_build
 docs/BNFLexer.pyc
 docs/EssenceLexer.pyc
 docs/__pycache__
+docs/myenv
 
 # to be used during development
 conjure-output

diff --git a/docs/bits.rst b/docs/bits.rst
@@ -0,0 +1,25 @@
+
+.. _bits:
+
+Bits
+====
+
+These *bits* of documentation are used in the Visual Studio Code extension for Conjure.
+Search for `conjure-vs-code` inside VS Code to install this extension.
+The extension is open source as well, and it is hosted at https://github.com/conjure-cp/conjure-vs-code.
+
+We include them here for reference and convenience, but this part of the documentation is intended to be useful primarily through the VS Code extension.
+
+.. toctree::
+
+  bits/attribute/L_regular.md
+  bits/function/min.md
+  bits/function/and.md
+  bits/function/max.md
+  bits/function/allDiff.md
+  bits/keyword/find.md
+  bits/keyword/expr_projection.md
+  bits/keyword/new_type_enum.md
+  bits/operator/L_Div.md
+  bits/operator/L_in.md
+  bits/operator/L_Mod.md
diff --git a/docs/bits/attribute/L_regular.md b/docs/bits/attribute/L_regular.md
@@ -1,3 +1,5 @@
-## `regular` : partition attribute
+# regular
+
 Regular is an attribute for partitions that takes no arguments.
+
 It enforces that the sizes of the parts are equal.
diff --git a/docs/bits/function/allDiff.md b/docs/bits/function/allDiff.md
@@ -1,4 +1,5 @@
-# AllDifferent
+# allDiff
+
 ```essence
 allDiff(_)
 ```

diff --git a/docs/bits/function/and.md b/docs/bits/function/and.md
@@ -1,3 +1,5 @@
+# and
+
 Conjunction (logical and) operator.
 
 Can be applied on a list of Booleans and produces a single Boolean as the result.
diff --git a/docs/bits/function/max.md b/docs/bits/function/max.md
@@ -1,4 +1,5 @@
-# Max
+# max
+
 ```essence
 max(expr) $or
 max(`domain`)

diff --git a/docs/bits/function/min.md b/docs/bits/function/min.md
@@ -1,4 +1,5 @@
-# Min
+# min
+
 ```essence
 min(expr) $or
 min(`domain`)

diff --git a/docs/bits/keyword/expr_projection.md b/docs/bits/keyword/expr_projection.md
@@ -1,4 +1,5 @@
-## Expression Projection `<-`
+# <- (expression projection)
+
 The expression projection syntax is used in comprehensions to create a generator from a container data type.
 The left side can either be a single variable which
 will have the type of a member of the expression or an abstract pattern used to destructure the member type.

diff --git a/docs/bits/keyword/find.md b/docs/bits/keyword/find.md
@@ -1,3 +1,3 @@
-## Find
+# find
 
 The `find` keyword is used to declare decision variables. 
diff --git a/docs/bits/keyword/new_type_enum.md b/docs/bits/keyword/new_type_enum.md
@@ -1,4 +1,5 @@
-## Enum Domains
+# new type enum
+
 Enumerated types can be declared in two ways: using a given-enum syntax or using a letting-enum syntax.
 
 The given-enum syntax defers the specification of actual values of the enumerated type until instantiation. With this syntax, an enumerated type can be declared by only giving its name in the problem specification file. In a parameter file, values for the actual members of this type can be given. This allows Conjure to produce a model independent of the values of the enumerated type and only substitute the actual values during parameter instantiation.

diff --git a/docs/bits/operator/L_Div.md b/docs/bits/operator/L_Div.md
@@ -1,3 +1,4 @@
+# / (integer division)
 
 This is the integer division operator.
 

diff --git a/docs/bits/operator/L_Mod.md b/docs/bits/operator/L_Mod.md
@@ -1,4 +1,5 @@
-**Mod operator**
+# % (modulo)
+
 ```
 %
 ```

diff --git a/docs/bits/operator/L_in.md b/docs/bits/operator/L_in.md
@@ -1,4 +1,5 @@
-## Operator in
+# in (membership check)
+
 ```essence
 in
 ```

diff --git a/docs/build.sh b/docs/build.sh
@@ -1,2 +1,6 @@
-python3 -m pip install -r requirements.txt
-python3 -m sphinx . _build
+rm -rf myenv
+python3 -m venv myenv
+source myenv/bin/activate
+pip install -r requirements.txt
+make html
+deactivate
diff --git a/docs/conf.py b/docs/conf.py
@@ -34,7 +34,8 @@
     'sphinx.ext.todo',
     'sphinxcontrib.bibtex',
     'sphinxcontrib.jquery',
-    'nbsphinx'
+    'nbsphinx',
+    'sphinx_mdinclude'
 ]
 bibtex_bibfiles = ['refs.bib']
 
@@ -43,8 +44,7 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -92,7 +92,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'myenv']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

diff --git a/docs/contact.rst b/docs/contact.rst
@@ -4,7 +4,7 @@
 Contact
 =======
 
-Conjure's main developer is `Özgür Akgün <http://ozgur.host.cs.st-andrews.ac.uk>`_.
+Conjure's main developer is `Özgür Akgün <ozgurakgun.github.io>`_.
 Please get in touch via `email <ozgur.akgun@st-andrews.ac.uk>`_ if you have comments, suggestions, or if you encounter any problems.
 
 You can also use the `issue tracker <https://github.com/conjure-cp/conjure/issues>`_ to report bugs.

diff --git a/docs/index.rst b/docs/index.rst
@@ -17,6 +17,7 @@ Conjure: The Automated Constraint Modelling Tool
     essence
     tutorials
     tutorials-notebook
+    bits
     zreferences
     contact
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,7 @@
+nbsphinx==0.9.3
+sphinx-mdinclude==0.5.3
+sphinx==7.2.6
+sphinx_rtd_theme==1.3.0
 sphinxcontrib-bibtex==2.5.0
 sphinxcontrib-inlinesyntaxhighlight==0.2
-sphinx_rtd_theme==1.2.0
-sphinx==6.1.3
-nbsphinx==0.9.1
+sphinxcontrib-jquery==4.1