diff --git a/Makefile b/Makefile index 4c7c31ac..3654a71b 100644 --- a/Makefile +++ b/Makefile @@ -2,11 +2,11 @@ # # You can set these variables from the command line. +PYTHON = python3 SPHINXOPTS = SPHINXBUILD = sphinx-build SPHINXPROJ = ODKX ODKX_SRCDIR = odkx-src -SHARED_SRCDIR = shared-src COMPILE_X_SRCDIR = tmpx-src ODKX_BUILDDIR = odkx-build @@ -32,7 +32,6 @@ clean: odkx-clean odkx-copy: odkx-clean-files mkdir $(COMPILE_X_SRCDIR) cp -rf $(ODKX_SRCDIR)/* $(COMPILE_X_SRCDIR) - cp -rf $(SHARED_SRCDIR)/* $(COMPILE_X_SRCDIR) odkx: odkx-copy @$(SPHINXBUILD) -b dirhtml "$(COMPILE_X_SRCDIR)" "$(ODKX_BUILDDIR)" $(SPHINXOPTS) @@ -44,7 +43,7 @@ build-all: odkx odkx-latex: odkx @$(SPHINXBUILD) -b latex "$(COMPILE_X_SRCDIR)" "$(ODKX_BUILDDIR)"/latex $(SPHINXOPTS) - python util/resize.py "$(ODKX_BUILDDIR)" + $(PYTHON) util/resize.py "$(ODKX_BUILDDIR)" odkx-pdf: odkx-latex cd "$(ODKX_BUILDDIR)"/latex && \ @@ -54,11 +53,11 @@ odkx-pdf: odkx-latex mv ODK-X.pdf ../_downloads/ODK-X-Documentation.pdf odkx-style-check: odkx - python style-test.py -r $(COMPILE_X_SRCDIR) + $(PYTHON) style-test.py -r $(COMPILE_X_SRCDIR) odkx-spell-check: odkx sphinx-build -b spelling $(COMPILE_X_SRCDIR) $(ODKX_BUILDDIR)/spelling - python util/check-spelling-output.py $(ODKX_BUILDDIR) + $(PYTHON) util/check-spelling-output.py $(ODKX_BUILDDIR) odkx-check: odkx-style-check odkx-spell-check diff --git a/README.md b/README.md index bd48f68f..a41e839d 100644 --- a/README.md +++ b/README.md @@ -39,10 +39,10 @@ It can take a long time (>10 minutes) to clone the repo due to the large number ### Building the Docker image -Next, you need to build the Docker image with all the tools you will be using to work with ODK's docs. +Next, you need to build the Docker image with all the tools you will be using to work with ODK-X's docs. ``` -docker build -t odk-docs . +docker build -t odkx-docs . ``` It can take a long time to build the Docker image, but you only need to do this once. @@ -63,10 +63,10 @@ Changes you make in the source files will automatically be built and shown in yo Press `Ctrl-C` on your keyboard to stop the build server. It could take a while to effectively stop, and you can always close the terminal window. -If you get a `The name "odk-docs" is already in use by container` error message, run the following command: +If you get a `The name "odkx-docs" is already in use by container` error message, run the following command: ``` -docker kill odk-docs +docker kill odkx-docs ``` ### Other build tasks @@ -91,62 +91,61 @@ We highly recommend you use a virtual environment like [virtualenv](https://virt .. _virtual environment: https://docs.python.org/3/tutorial/venv.html - #. Create the virtual environment. - - .. tabs:: - - .. group-tab:: Bash + #. Create a directory called 'odkx' + Create a directory for the documents. For the purposes of these directions we will use the folder 'odkx' as the directory that will contain the ODK-X Docs environment. + - .. code:: console + mkdir odkx + + + Next, navigate the command line interface to inside the directory. + + + cd odkx - /odk/ $ python3 -m venv odkenv - .. group-tab:: PowerShell + #. Create the virtual environment. - .. code:: powershell - /odk/ > python -m venv odkenv + + Next create the virtual environment inside the 'odkx' directory. + + Bash - #. Activate the virtual environment. + /odkx/ $ python3 -m venv odkxenv - .. tabs:: + PowerShell - .. group-tab:: Bash - - .. code:: console + /odkx/ > python -m venv odkxenv - /odk/ $ source odkenv/bin/activate - (odkenv) /odk/ $ - - .. group-tab:: PowerShell + #. Activate the virtual environment. - .. code:: console + Bash + + /odkx/ $ source odkxenv/bin/activate + (odkxenv) /odkx/ $ - /odk/ > source odkenv/bin/activate - (odkenv) /odk/ > + PowerShell + + /odkx/ > source odkxenv/bin/activate + (odkxenv) /odkx/ > - The ``(odkenv)`` before the prompt shows that the virtual environment is active. + The ``(odkxenv)`` before the prompt shows that the virtual environment is active. You will need to have this active any time you are working on the docs. - If the file cannot be found, your activate file may be located under odkenv/scripts/activate. + If the file cannot be found, your activate file may be located under odkxenv/scripts/activate. Later, to deactivate the virtual environment: - .. tabs:: - - .. group-tab:: Bash - - .. code:: console - - (odkenv) /odk/ $ deactivate - /odk/ $ + Bash - .. group-tab:: PowerShell + (odkxenv) /odkx/ $ deactivate + /odkx/ $ - .. code:: console + PowerShell - (odkenv) /odk/ > deactivate - /odk/ > + (odkxenv) /odkx/ > deactivate + /odkx/ > ### Cloning the repo @@ -188,8 +187,7 @@ We are open for new issues and pull requests. - Please read the [Contributors Guide](https://docs.odk-x.org/contributing) before working on the documentation. - Find issues to work on. - - First time contributors are encouraged to complete a [line edit](https://github.com/getodk/docs/issues/96) as a way to get familiar with our contribution process. - - Issues labelled [easy](https://github.com/odk-x/docs/labels/easy) do not require much specific technical knowledge. + - Issues labelled [easy](https://github.com/odk-x/docs/labels/easy) do not require much specific technical knowledge. - Issues labelled [contributor friendly](https://github.com/odk-x/docs/labels/contributor%20friendly) are usually self-contained and don't require extensive knowledge of the ODK-X ecosystem as a whole. You can also... diff --git a/shared-src/_static/img/favicon.ico b/odkx-src/_static/img/favicon.ico similarity index 100% rename from shared-src/_static/img/favicon.ico rename to odkx-src/_static/img/favicon.ico diff --git a/shared-src/_static/img/logo-wide.png b/odkx-src/_static/img/logo-wide.png similarity index 100% rename from shared-src/_static/img/logo-wide.png rename to odkx-src/_static/img/logo-wide.png diff --git a/shared-src/_static/img/logo.png b/odkx-src/_static/img/logo.png similarity index 100% rename from shared-src/_static/img/logo.png rename to odkx-src/_static/img/logo.png diff --git a/shared-src/_static/js/custom.js b/odkx-src/_static/js/custom.js similarity index 98% rename from shared-src/_static/js/custom.js rename to odkx-src/_static/js/custom.js index 3f1ef95c..5f6f678b 100644 --- a/shared-src/_static/js/custom.js +++ b/odkx-src/_static/js/custom.js @@ -1,4 +1,3 @@ -// This JS file is in shared-src. // Implement Details-like hide/show on class "details" $(function(){ diff --git a/shared-src/_templates/footer.html b/odkx-src/_templates/footer.html similarity index 83% rename from shared-src/_templates/footer.html rename to odkx-src/_templates/footer.html index c74bb79c..bc23ccd2 100644 --- a/shared-src/_templates/footer.html +++ b/odkx-src/_templates/footer.html @@ -11,11 +11,20 @@ {% endif %}
{%- if show_copyright %}
diff --git a/shared-src/_templates/layout.html b/odkx-src/_templates/layout.html
similarity index 100%
rename from shared-src/_templates/layout.html
rename to odkx-src/_templates/layout.html
diff --git a/odkx-src/conf.py b/odkx-src/conf.py
index 3d5b9e56..f8d3a137 100755
--- a/odkx-src/conf.py
+++ b/odkx-src/conf.py
@@ -249,14 +249,14 @@
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
# 'py': ('https://docs.python.org/', None),
- 'odk1': ('https://docs.odk-x.org/', None)
+ 'odkx': ('https://docs.odk-x.org/', None)
}
# Add custom CSS
def setup(app):
- app.add_stylesheet('css/custom.css')
- app.add_javascript('js/custom.js')
+ app.add_css_file('css/custom.css')
+ app.add_js_file('js/custom.js')
# At top of every document
@@ -280,7 +280,7 @@ def setup(app):
Download this documentation as a PDF.
"""
-odk_pdf = """
+odkx_pdf = """
_downloads/ODK-X-Documentation.pdf
@@ -360,7 +360,7 @@ def setup(app):
"""
html_context = {'download_pdf' : download_pdf,
- 'odk_pdf' : odk_pdf,
+ 'odkx_pdf' : odkx_pdf,
'prob_in_doc' : prob_in_doc ,
'contri_start' : contri_start ,
'join' : join ,
@@ -374,7 +374,7 @@ def setup(app):
'contri_guide' : contri_guide ,
'forum_here' : forum_here ,
'display_github' : True,
- 'github_user' : "opendatakit", # Username
+ 'github_user' : "odk-x", # Username
'github_repo' : "docs", # Repo name
'github_version' : "master", # Version
'conf_py_path' : "/odkx-src/" # Path in the checkout to the docs root
diff --git a/shared-src/contributing-tips.rst b/odkx-src/contributing-tips.rst
similarity index 100%
rename from shared-src/contributing-tips.rst
rename to odkx-src/contributing-tips.rst
diff --git a/shared-src/contributing.rst b/odkx-src/contributing.rst
similarity index 100%
rename from shared-src/contributing.rst
rename to odkx-src/contributing.rst
diff --git a/shared-src/cygwin.rst b/odkx-src/cygwin.rst
similarity index 100%
rename from shared-src/cygwin.rst
rename to odkx-src/cygwin.rst
diff --git a/shared-src/docs-developer-guide.rst b/odkx-src/docs-developer-guide.rst
similarity index 100%
rename from shared-src/docs-developer-guide.rst
rename to odkx-src/docs-developer-guide.rst
diff --git a/shared-src/docs-extras.rst.scratch b/odkx-src/docs-extras.rst.scratch
similarity index 100%
rename from shared-src/docs-extras.rst.scratch
rename to odkx-src/docs-extras.rst.scratch
diff --git a/shared-src/docs-style-guide.rst b/odkx-src/docs-style-guide.rst
similarity index 100%
rename from shared-src/docs-style-guide.rst
rename to odkx-src/docs-style-guide.rst
diff --git a/shared-src/docs-syntax-guide.rst b/odkx-src/docs-syntax-guide.rst
similarity index 100%
rename from shared-src/docs-syntax-guide.rst
rename to odkx-src/docs-syntax-guide.rst
diff --git a/shared-src/docs-tech-guide.rst b/odkx-src/docs-tech-guide.rst
similarity index 94%
rename from shared-src/docs-tech-guide.rst
rename to odkx-src/docs-tech-guide.rst
index c422b528..aba3ef95 100644
--- a/shared-src/docs-tech-guide.rst
+++ b/odkx-src/docs-tech-guide.rst
@@ -1053,15 +1053,10 @@ Working on the docs
Finally, you can open an :ref:`editor of your choice