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 %}
-

{{ download_pdf }}

+

{{ download_pdf }}

{{ faq_help }} {{ forum }}

{{ prob_in_doc }} {{ file_issue }}

{{ contri_start }} {{ fork_repo }} {{ join }} {{ contri }}

+
+ + + +

{%- 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 ` and work on the documentation. - The source files for documentation text are in these directories: + The source files for documentation text are in these directory: - :file:`odk1-src` - Files for the pages at https://docs.odk-x.org :file:`odkx-src` - Files for the pages at https://docs.odk-x.org/odk-x - :file:`shared-src` - Files for pages shared by both ODK1 and ODK-X docs. - (This page and the other contributor guide pages.) + Files for the pages at https://docs.odk-x.org/ If you're going to write or edit documentation text, please read: @@ -1084,36 +1079,13 @@ Working on the docs you should run the tests locally first and correct any problems. - If you've been working on files in :file:`odk1-src` or :file:`shared-src`: - - .. tabs:: - - .. group-tab:: Bash - - .. code:: console - - (odkenv) /odk/docs/ $ make odk1-check - - .. group-tab:: PowerShell - - .. code:: powershell - - (odkenv) /odk/docs/ > rm -r -fo tmp1-src - (odkenv) /odk/docs/ > rm -r -fo odk1-build - (odkenv) /odk/docs/ > Copy-Item odk1-src -Destination tmp1-src -Recurse - (odkenv) /odk/docs/ > Copy-Item shared-src -Destination tmp1-src -Recurse - (odkenv) /odk/docs/ > sphinx-build -b spelling tmp1-src odk1-build/spelling - (odkenv) /odk/docs/ > python util/check-spelling-output.py odk1-build - - If you've been working on files in :file:`odkx-src`: - .. tabs:: .. group-tab:: Bash .. code:: console - (odkenv) /odk/docs/ $ make odkx-spell-check + (odkenv) /odk/docs/ $ make odkx-check .. group-tab:: PowerShell @@ -1122,8 +1094,7 @@ Working on the docs (odkenv) /odk/docs/ > rm -r -fo tmpx-src (odkenv) /odk/docs/ > rm -r -fo odkx-build (odkenv) /odk/docs/ > Copy-Item odkx-src -Destination tmpx-src -Recurse - (odkenv) /odk/docs/ > Copy-Item shared-src -Destination tmpx-src -Recurse - (odkenv) /odk/docs/ > sphinx-build -b spelling tmp1-src odkx-build/spelling + (odkenv) /odk/docs/ > sphinx-build -b spelling tmpx-src odkx-build/spelling (odkenv) /odk/docs/ > python util/check-spelling-output.py odkx-build @@ -1164,28 +1135,6 @@ Working on the docs .. _Sphinx: http://www.sphinx-doc.org - If you've been working on files in :file:`odk1-src` or :file:`shared-src`: - - .. tabs:: - - .. group-tab:: Bash - - .. code:: console - - (odkenv) /odk/docs/ $ make odk1 - - .. group-tab:: PowerShell - - .. code:: powershell - - (odkenv) /odk/docs/ > rm -r -fo tmp1-src - (odkenv) /odk/docs/ > rm -r -fo odk1-build - (odkenv) /odk/docs/ > Copy-Item odk1-src -Destination tmp1-src -Recurse - (odkenv) /odk/docs/ > Copy-Item shared-src -Destination tmp1-src -Recurse - (odkenv) /odk/docs/ > sphinx-build -b dirhtml tmp1-src odk1-build - - If you've been working on files in :file:`odkx-src`: - .. tabs:: .. group-tab:: Bash @@ -1201,7 +1150,6 @@ Working on the docs (odkenv) /odk/docs/ > rm -r -fo tmpx-src (odkenv) /odk/docs/ > rm -r -fo odkx-build (odkenv) /odk/docs/ > Copy-Item odkx-src -Destination tmpx-src -Recurse - (odkenv) /odk/docs/ > Copy-Item shared-src -Destination tmpx-src -Recurse (odkenv) /odk/docs/ > sphinx-build -b dirhtml tmpx-src odkx-build This generates a lot of output. @@ -1248,7 +1196,7 @@ Working on the docs The warning messages will refer to the file name using the temporary directory path :file:`tmp1-src` or :file:`tmpx-src`. You need to correct the problems in the real source directory - (:file:`odk1-src`, :file:`odkx-src`, or :file:`shared-src`). + (:file:`odkx-src`). .. admonition:: When you just can't fix the error... @@ -1265,26 +1213,6 @@ Working on the docs .. _serve-the-docs-locally: - If you've been working on files in :file:`odk1-src` or :file:`shared-src`: - - .. tabs:: - - .. group-tab:: Bash - - .. code:: console - - (odkenv) /odk/docs/ $ python -m http.server -d odk-build 8000 - Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) - - .. group-tab:: PowerShell - - .. code:: powershell - - (odkenv) /odk/docs/ > python -m http.server -d odk1-build 8000 - Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) - - If you've been working on files in :file:`odkx-src`: - .. tabs:: .. group-tab:: Bash diff --git a/shared-src/img/cygwin/pip-install.png b/odkx-src/img/cygwin/pip-install.png similarity index 100% rename from shared-src/img/cygwin/pip-install.png rename to odkx-src/img/cygwin/pip-install.png diff --git a/shared-src/img/cygwin/python-path.png b/odkx-src/img/cygwin/python-path.png similarity index 100% rename from shared-src/img/cygwin/python-path.png rename to odkx-src/img/cygwin/python-path.png diff --git a/shared-src/img/docs-tech-guide/terminal-icon.png b/odkx-src/img/docs-tech-guide/terminal-icon.png similarity index 100% rename from shared-src/img/docs-tech-guide/terminal-icon.png rename to odkx-src/img/docs-tech-guide/terminal-icon.png diff --git a/shared-src/spelling_wordlist.txt b/odkx-src/spelling_wordlist.txt similarity index 100% rename from shared-src/spelling_wordlist.txt rename to odkx-src/spelling_wordlist.txt diff --git a/requirements.txt b/requirements.txt index cd7c56db..f58c691d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,44 +1,46 @@ -alabaster==0.7.10 +alabaster==0.7.12 argh==0.26.2 -atomicwrites==1.2.1 -attrs==18.2.0 -Babel==2.4.0 +Babel==2.8.0 blessings==1.7 -Click==7.0 -coverage==4.5.1 -docutils==0.14 -future==0.16.0 -gitdb2==2.0.4 -GitPython==2.1.11 -hypothesis==3.69.1 -imagesize==0.7.1 -Jinja2==2.10.1 -livereload==2.5.2 +certifi==2020.6.20 +chardet==3.0.4 +click==7.1.2 +docutils==0.16 +future==0.18.2 +gitdb==4.0.5 +GitPython==3.1.8 +idna==2.10 +imagesize==1.2.0 +importlib-metadata==2.0.0 +Jinja2==2.11.2 +livereload==2.6.3 MarkupSafe==1.1.1 -more-itertools==4.3.0 -olefile==0.46 +packaging==20.4 pathtools==0.1.2 -Pillow>=4.3.0 -pluggy==0.7.1 port-for==0.3.1 proselint==0.10.2 -py==1.6.0 -pyenchant==2.0.0 -Pygments==2.2.0 -pytest==3.7.2 -pytz==2017.2 -PyYAML==4.2b1 -requests==2.20.0 -six==1.10.0 -smmap2==2.0.4 -snowballstemmer==1.2.1 +pyenchant==3.1.1 +Pygments==2.7.1 +pyparsing==2.4.7 +pytz==2020.1 +PyYAML==5.3.1 +requests==2.24.0 +Send2Trash==1.5.0 +six==1.15.0 +smmap==3.0.4 +snowballstemmer==2.0.0 +Sphinx==3.2.1 sphinx-autobuild==0.7.1 -sphinx-rtd-theme==0.4.1 -sphinx-tabs==1.1.7 -Sphinx==1.6.6 -sphinx_fontawesome==0.0.6 -sphinxcontrib-spelling==4.2.0 -sphinxcontrib-websupport==1.0.1 -tornado==5.1.1 -typing==3.6.1 -watchdog==0.9.0 +sphinx-rtd-theme==0.5.0 +sphinx-tabs==1.1.13 +sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==1.0.3 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.4 +sphinxcontrib-spelling==5.4.0 +tornado==6.0.4 +urllib3==1.25.10 +watchdog==0.10.3 +zipp==1.2.0 diff --git a/run-task.bat b/run-task.bat index 21c88a2f..e6a0e141 100644 --- a/run-task.bat +++ b/run-task.bat @@ -1 +1 @@ -docker run --rm -v %~dp0:/mnt -p 8080:8080 --name odk-docs odk-docs %1 +docker run --rm -v %~dp0:/mnt -p 8080:8080 --name odkx-docs odkx-docs %1 diff --git a/run-task.sh b/run-task.sh index e46efec7..4686f796 100755 --- a/run-task.sh +++ b/run-task.sh @@ -2,4 +2,4 @@ DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )" -docker run --rm -v "${DIR}":/mnt -p 8080:8080 --name odk-docs odk-docs "$1" +docker run --rm -v "${DIR}":/mnt -p 8080:8080 --name odkx-docs odkx-docs "$1" diff --git a/style-test.py b/style-test.py index 9c18da37..b6325aa4 100644 --- a/style-test.py +++ b/style-test.py @@ -49,7 +49,7 @@ def is_extra_code_block(node): and 'python' in node.attributes['classes'] and 'extra-checks' in node.attributes['classes']) - style_guide = open(dir_path + "/shared-src/docs-style-guide.rst", "r") + style_guide = open(dir_path + "/odkx-src/docs-style-guide.rst", "r") # publish doctree, report only severe errors doctree = publish_doctree(style_guide.read(), diff --git a/util/check-spelling-output.py b/util/check-spelling-output.py index ef590b5b..0ebbfdd6 100644 --- a/util/check-spelling-output.py +++ b/util/check-spelling-output.py @@ -6,23 +6,20 @@ import os import sys + class SpellingError(ValueError): pass + if len(sys.argv) < 2: raise ValueError("The parent directory of the spelling directory is a required argument") build_dir = sys.argv[1] spelling_dir = "spelling" -output_file = "output.txt" -output_path = os.path.join(build_dir, spelling_dir, output_file) +output_path = os.path.join(build_dir, spelling_dir) -try: - assert os.stat(output_path).st_size == 0 -except AssertionError: - with open(output_path, 'r') as f: - print(f.read()) - raise SpellingError("You have spelling errors.") from AssertionError -else: - print("No spelling errors caught.") +for each in os.listdir(output_path): + if each.endswith('.spelling'): + raise SpellingError("You have spelling errors.") + break diff --git a/video.py b/video.py index 5a03774b..529db46e 100644 --- a/video.py +++ b/video.py @@ -3,7 +3,7 @@ import sphinx.environment from docutils import nodes from docutils.parsers.rst import directives -from sphinx.util.compat import Directive +from docutils.parsers.rst import Directive def yes_no(name, arg): @@ -31,18 +31,13 @@ def visit_video_html(self, node): vsrc = node["uri"] spth = srcPath % vsrc - if "tmp1-src" not in spth: - if os.path.exists("./odkx-build/_videos"): - pass - else: - os.makedirs("./odkx-build/_videos/") - dpth = "./odkx-build/_videos/%s" %vsrc[vsrc.rfind('/')+1:] + + if os.path.exists("./odkx-build/_videos"): + pass else: - if os.path.exists("./odk1-build/_videos"): - pass - else: - os.makedirs("./odk1-build/_videos/") - dpth = "./odk1-build/_videos/%s" %vsrc[vsrc.rfind('/')+1:] + os.makedirs("./odkx-build/_videos/") + + dpth = "./odkx-build/_videos/%s" %vsrc[vsrc.rfind('/')+1:] shutil.copyfile(spth, dpth)