From e425e1b2719ca838d8e7ba3088cb0a2da95000ff Mon Sep 17 00:00:00 2001 From: Adam Michael Wood Date: Tue, 21 Aug 2018 14:59:40 -0400 Subject: [PATCH 1/6] Add a note to the JS file for testing. --- shared-src/_static/js/custom.js | 1 + 1 file changed, 1 insertion(+) diff --git a/shared-src/_static/js/custom.js b/shared-src/_static/js/custom.js index 5f6f678b7..3f1ef95cb 100644 --- a/shared-src/_static/js/custom.js +++ b/shared-src/_static/js/custom.js @@ -1,3 +1,4 @@ +// This JS file is in shared-src. // Implement Details-like hide/show on class "details" $(function(){ From 57997de68d4193c87698b9387f397ee59b2070d5 Mon Sep 17 00:00:00 2001 From: Adam Michael Wood Date: Tue, 11 Sep 2018 10:56:39 -0700 Subject: [PATCH 2/6] add vscode config files to gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 1de72599d..b685134ee 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,6 @@ tmp* # literate programming style-checks.py extra.py + +# vscode +.vscode From f793be4afb5812e513ef90d0fa3373717eb77e63 Mon Sep 17 00:00:00 2001 From: Adam Michael Wood Date: Tue, 11 Sep 2018 10:58:07 -0700 Subject: [PATCH 3/6] make Pillow req flexible above 4.3, as 4.3.0 has a pip install problem --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index d784e5f81..9496071f5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -14,7 +14,7 @@ sphinx-rtd-theme==0.2.4 sphinxcontrib-websupport==1.0.1 sphinxcontrib-spelling typing==3.6.1 -Pillow==4.3.0 +Pillow>=4.3.0 proselint blessings gitpython From 0e4b65b08565a798f400c3937d42f6f78e89aca4 Mon Sep 17 00:00:00 2001 From: Adam Michael Wood Date: Tue, 11 Sep 2018 10:58:52 -0700 Subject: [PATCH 4/6] completely rewrite docs tech guide --- odk1-src/conf.py | 3 + shared-src/docs-developer-guide.rst | 16 + shared-src/docs-extras.rst.scratch | 52 + shared-src/docs-tech-guide.rst | 1851 +++++++++++------ .../img/docs-tech-guide/terminal-icon.png | 3 + 5 files changed, 1241 insertions(+), 684 deletions(-) create mode 100644 shared-src/docs-extras.rst.scratch create mode 100644 shared-src/img/docs-tech-guide/terminal-icon.png diff --git a/odk1-src/conf.py b/odk1-src/conf.py index 3d5f78775..ea2dad955 100755 --- a/odk1-src/conf.py +++ b/odk1-src/conf.py @@ -281,6 +281,9 @@ def setup(app): .. role:: arg :class: arg """ +# if you add lines to rst_prolog, +# please update the note about warnings offsets +# in shared-src/docs-tech-guide.rst # At bottom of every document download_pdf = """ diff --git a/shared-src/docs-developer-guide.rst b/shared-src/docs-developer-guide.rst index 0940b1c70..5a1180f1d 100644 --- a/shared-src/docs-developer-guide.rst +++ b/shared-src/docs-developer-guide.rst @@ -340,3 +340,19 @@ To exclude an built-in proselint check, specify the check name in the check list in the function :py:func:`exclude_checks` in the file :file:`style-test.py`. + + + + + + + +.. + If you are working on + the design, testing, or deployment of the docs, + you might need to install an additional PyPi package. + If so, + please update the :file:`requirements.txt` file with + :command:`pip freeze > requirements.txt`. + Pull requests which change :file:`requirements.txt` + should include a note about why the new package is needed. \ No newline at end of file diff --git a/shared-src/docs-extras.rst.scratch b/shared-src/docs-extras.rst.scratch new file mode 100644 index 000000000..9849e0577 --- /dev/null +++ b/shared-src/docs-extras.rst.scratch @@ -0,0 +1,52 @@ + Ideally, each issue represents a single small project + to fix one well-defined problem with the documentation. + Examples of well-defined single issues include: + + - Write a section to the form questions document describing new type of question + - Fix the formatting in the contributor's guide + - Redirect old page URI to new + - Add style testing for ODK2 branding + - Change the display font + + As these examples show, documentation projects include: + + - writing new documentation + - editing existing documentation + - coding related to the design of the documentation website + - coding related to how the documentation is built, tested, and published + + This means that, whatever your skill or interest, + there is probably an issue you can work on. + + Sometimes, issues are not well defined yet. + This might be because we only have a vague idea of a need, + or because we're not yet sure how to solve a problem, + or because no one has had the time to write down the details. + As you are getting started, + try to focus on issues that have a clear goal. + Once you have some experience with the documentation, + you can start to help clarify issues so we can move forward on them. + + + + + + +.. note:: + + If you rename a document file (:file:`*.rst`), + be sure that you add the redirect in your PR. + + To add the redirect, go to :file:`s3_website.yml`, + and add a mapping from the old file name to the new file name + below the **redirects:** line, one mapping per line. + + If you have renamed :file:`old-name.rst` to :file:`new-name.rst`: + + .. code-block:: yaml + + redirects: + old-name/index.html: new-name + + Notice the inclusion of ``/index.html`` on the left side. + diff --git a/shared-src/docs-tech-guide.rst b/shared-src/docs-tech-guide.rst index 78e85ed10..ccc16e837 100644 --- a/shared-src/docs-tech-guide.rst +++ b/shared-src/docs-tech-guide.rst @@ -5,8 +5,8 @@ Docs Technical Guide ========================== -This document explains the tools and workflows used -when contributing to ODK Documentation. +This document explains how to contribute to +ODK Docs. .. note:: @@ -14,1057 +14,1540 @@ when contributing to ODK Documentation. have a lot of options and alternatives. Local tools and workflows presented in this guide are what the authors feel would be easiest - for a non-coding contributor to set up and use. + for newcomers and those unfamiliar with open source. You should feel free to use your preferred tools. -.. _docs-as-code: +.. _docs-before-you-begin: -Docs as Code +Before you begin ---------------- -ODK Documentation follows -(as much as possible) -the `Docs as Code`_ philosophy. +.. _learn-about-odk: -.. _Docs as Code: http://www.writethedocs.org/guide/docs-as-code/ +Learn a little about Open Data Kit +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This means: +Read about the project and the community at `Open Data Kit's website`_. -- Documentation source files are written in a plain text format. - (We use `reStructuredText`_.) -- Documentation source files are kept under version control. - (We use git and `Github`_.) -- Documentation is built from source - to a published output using a - static site generator. - (We use `Sphinx`_.) -- Documentation builds are - run, tested, and deployed automatically - using continuous integration tools. - (We use `CircleCI`_.) +.. _odk-accounts: -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Github: http://github.com -.. _Sphinx: http://sphinx-doc.org -.. _CircleCI: https://circleci.com +Set up collaboration accounts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'Docs as Code' approach has many advantages, -but we are aware that this approach can feel difficult -for writers who aren't used to dealing with the command line. -It can also be difficult for coders who are used to this approach, -but who typically use simpler authoring tools -like `Jekyll`_ and `Markdown`_. +Open Data Kit is a collaborative community. +Before diving in as a contributor, +set up accounts on our three main collaboration platforms, +:ref:`GitHub `, +the :ref:`ODK Developer Slack `, +and the :ref:`ODK Forum ` -.. _Jekyll: http://jekyllrb.com -.. _Markdown: https://guides.github.com/features/mastering-markdown/ +.. tip:: + + As you are setting up your accounts, + keep in mind that it is very helpful (but not required) + to use the same (or similar) username + on :ref:`GitHub `, + the :ref:`ODK Developer Slack `, + and the :ref:`ODK Forum `. -This section of the Contributor Guide -walks through our authoring and publishing workflow and toolchain, -to make it as easy as possible for you to contribute. + This makes it easy for other people to keep track of conversations + which sometimes span multiple online platforms. -.. _docs-workflow-overview: + If you are willing and able to do so, + a profile picture in each place is also very helpful. + (But it is okay if you are unable or uncomfortable + adding a picture.) -Overview of Workflow ------------------------ +.. _get-gh-account: +#. Set up a `GitHub`_ account. -When you first get started you'll need to: + `GitHub`_ is a popular code storage and collaboration platform. + You will need a GitHub account to contribute to Open Date Kit documentation, + or any other Open Date Kit projects. -1. Fork the `ODK Docs repo`_ to your own Github Account -2. Clone it down to your local machine -3. Install dependencies + - `Open Data Kit on GitHub`_ + - `ODK Docs on GitHub`_ -.. _ODK Docs repo: https://github.com/opendatakit/docs + .. _Open Data Kit on GitHub: https://github.com/opendatakit/ + .. _ODK Docs on GitHub: https://github.com/opendatakit/docs + .. _GitHub: https://github.com/ -And then each time you work you will: +.. _join-slack: +#. Join the `ODK Developer Slack`_. -1. Make a branch for a specific task -2. Make commits as you go -3. Build and view the docs locally, - running the style guide tests. + Slack is a popular chat platform. + The Open Data Kit contributor community uses Slack + to discuss development, plan work, and generally keep in touch. + If you have a question about how to contribute to ODK Docs, + or any other ODK project, + the ODK Slack is the best place to ask it. - - Correct any errors - and commit those changes + Conversations related to documentation are held in the ``#docs-code`` channel. + You may also want to check in with ``#general`` and ``#random``. -4. Push your branch to your Github fork -5. Issue a pull request - against the current working branch - of the main repo (usually ``master``) -6. Pull the latest changes to ``master`` - back to your local machine from the main repo. -7. Repeat + #. Get an automated invitation from http://slack.opendatakit.org + #. Check your email for the invitation. + #. Follow the link in your email and set up your account. -.. _docs-dev-setup: + .. _ODK Developer Slack: http://slack.opendatakit.org/ -Setting up your Environment ----------------------------- + .. tip:: + + It is helpful (but not required) to use the same (or similar) username + on Slack that you use on :ref:`Github ` + and the :ref:`ODK Forum `. -.. _docs-terminal: + This makes it easy for other people to keep track of conversations + which sometimes span multiple online platforms. -Terminal (Command Line) -~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If you are willing and able to do so, + a profile picture is also very helpful. + (But it is okay if you are unable or uncomfortable + adding a picture.) -.. warning:: +.. _join-forum: +#. Join the `ODK Forum`_ - This contributor guide is written - from a Linux/Unix (Bash terminal) perspective, - which is relevant to all flavors of Linux and macOS. - We consider the Bash terminal commands to be - the canonical way to build and work with the docs. + The `Open Data Kit Forum `_ is the main place for + support questions and conversations that affect the whole ODK community + (users and other stake holders, as well as contributors). - We have also provided explanations for - how to adapt these commands to the Windows Command Prompt. - This is different than Windows Powershell, - and not all the commands will work in Powershell. - For more details on the Windows Command Prompt, - `see this article`__. - - __ https://www.lifewire.com/how-to-open-command-prompt-2618089 + If you have a question about how to use any ODK software, + or want to get connected with the larger ODK community, + the forum is the best venue for that. - If you are on a Windows machine, - you may prefer to use the adapted Windows instructions here. - Alternatively, you can follow the Bash commands: + .. tip:: - - use the `Linux subsystem`_ (Windows 10) - - use a bash terminal emulator, such as + The forum has a search feature, and a long history of archived support posts. + When writing new documentation about an existing feature, + old forum posts are an excellent source for figuring out what people need to know: + If someone has asked a question about it, + it should probably be in the documentation. - - :doc:`Cygwin ` - - `gitbash`_ - - .. _Linux subsystem: https://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/ - .. _gitbash: https://git-for-windows.github.io/ - - The lead maintainers of this docs repo - are not Windows users, - so we rely on our contributor community - to keep Windows-specific information complete and accurate. - Contributions to this guide - with explanations and help for Windows users - are greatly appreciated. + .. _ODK Forum: http://forum.opendatakit.org - -Contributing to the docs requires interacting with -git, GitHub, Python, and Sphinx, -which requires the use of the Terminal. -This is common among Linux users. -Mac users unfamiliar with the Terminal -can learn more from `this tutorial`__. +.. _forum-or-slack-or-gh: +.. tip:: -__ https://computers.tutsplus.com/tutorials/navigating-the-terminal-a-gentle-introduction--mac-3855 + .. rubric:: Should I ask in the Forum, the Slack, or a GitHub issue? -.. _docs-python: + The ODK community talks a lot, in a lot of places. + Sometimes it's hard to know where to ask a question. -Python -~~~~~~~~ + **Contribution-related questions and problems should be asked in Slack.** + This includes things like: -.. _docs-python3: + - How do I set up my local editing environment? + - How do I use git? + - I'm having a merge conflict. + - I got an error at the terminal which I don't understand. + - How do I add a picture to a document? + - What issue should I work on? -Python 3 -"""""""""""" + **Work-specific questions and discussion should take place on the GitHub issue defining the work.** + This includes things like: -If you don't know, -check to see if you have Python 3 installed: + - I'm writing a piece of content, but I'm not sure where it should be organized. + - I'd like to work on this feature, but I don't know how to implement it. + - Here's my idea for solving this problem. Is that a good idea? + - I'm going to be working on this for the next few days. + No one else should also work on it at the same time. + - I said I was working on this, but I didn't finish and I'm no longer working on it. + **User-related questions and problems should be asked in the Forum.** + (You should use the search feature first, + since someone else may have already asked the same question.) + This includes things like: -.. code-block:: console + - How do I install an ODK application? + - How do I create a form? + - How do I add a specific feature to a form? + - My ODK application crashed. - $ python3 + ------ -On windows: + But don't worry about posting a question in the wrong place. + It is better to ask a question in the "wrong" venue + than to not ask the question at all. + Many of the same people are present in all three places, + and we will help you wherever you happen to show up. -.. code-block:: doscon +.. _docs-local-setup: - > python +Initial Setup +------------- +Before you begin working the first time +you will need to install a few tools +on your computer. -If you get an error, -you probably don't have it and will need to -`install Python 3`__. +You should only need to do this one time +on any computer. -__ https://www.python.org/downloads/ +#. Find and open a terminal or command line. -On Windows -make sure to select the option -"Add python to the Path" -while installing, -otherwise you'll need to `add it manually`__. + .. tabs:: + + .. group-tab:: Windows + + .. rubric:: Windows version prior to Windows 10 -__ https://youtu.be/UTUlp6L2zkw + Use `Windows PowerShell`_. (Not the DOS Prompt.) -See `this video`__ for more details. + .. _Windows PowerShell: https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershel -__ https://www.youtube.com/watch?v=oHOiqFs_x8Y + We recommend using the :program:`Windows PowerShell ISE`. -If the Python command-line interpreter starts up, -type :py:func:`quit()` to exit. + During initial setup (this section of the guide) + you will need to `Run as Administrator`_. -.. _docs-venv: + .. _Run as Administrator: https://docs.microsoft.com/en-us/powershell/scripting/setup/starting-windows-powershell?view=powershell-6#with-administrative-privileges-run-as-administrator -Virtual Environment -"""""""""""""""""""""""" + Throughout the rest of the instructions in this guide, + follow the instructions labelled **PowerShell** or **Windows**. -A virtual environment is a Python tool for sandboxing dependencies. -It lets you install whatever you need for a particular project, -without messing up any other Python environments you might need. + .. rubric:: Windows 10 -Check to see if you have virtualenv installed: + In Windows 10, you have a choice: -.. code-block:: console + - Use the Powershell (as described above) + - Use the `Windows Subsystem for Linux`_. - $ virtualenv + .. _Windows Subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/install-win10 -If you get a help message with information about commands, -you have it. -If you don't have it, -you'll get a ``command not found`` message. + If you decide to use the Powershell, + follow the **Powershell** or **Windows** instructions + throughout the contributor guides. -If you don't have it, -install it using ``pip`` by running: + If you decide to use the Linux subsystem, + follow the **Bash** or **Windows** instructions + throughout the contributor guide. -.. code-block:: console - $ pip install virtualenv + .. group-tab:: Mac + + Use the :program:`Terminal` app, + or another Bash-like shell. + + .. image:: /img/docs-tech-guide/terminal-icon.* + :alt: The Terminal Icon in Mac OS. + + If you've never used it before, + the Terminal is probably in the :guilabel:`Other` directory + in your App collection. + + Follow the **Bash** or **Mac** instructions + throughout the contributor guide. + + .. rubric: Install Homebrew + + `Homebrew`_ is a :term:`package manager` for Mac OS. + It makes it easier to install other apps and tools + from the command line. + + Follow the `installation instructions`_. + + .. _Homebrew: https://brew.sh/ + .. _installation instructions: Homebrew + + .. group-tab:: Linux + + Use a Bash-like shell of your choosing, + and follow the **Bash** or **Linux** instructions + throughout the contributor guide. + + You will also need to be familiar with + the relevant package manager for your system. + + .. admonition: Understanding terminal commands + :name: understanding-terminal + + When you open the Terminal or PowerShell, + you will see a bunch of symbols that include + your username and computer name. + This is called the :term:`prompt`. + You type commands after the prompt, + and hit :kbd:`RETURN` or :kbd:`ENTER` to run that command. + + Everybody's prompt looks different, + so we can't make our documentation match what you see. + Instead, we use the ``$`` symbol to represent the Bash prompt + and the ``>`` symbol to represent the PowerShell prompt. + The text that follows the ``$`` or ``>`` symbol + is the command you need to type or copy. + + Below the command, there is sometimes output from the command. + + .. tabs:: + + .. group-tab:: bash + + .. code-block:: + + $ command is here - type this + Output is here. Don't type this. + + .. group-tab:: PowerShell + + .. code-block:: + + > command is here - type this + Output is here. Don't type this. + + Not all commands have output, + and we don't always include the output in our documentation + unless it is relevant. + It it is a good idea to glance at your own terminals output + for unexpected errors. + + To make things more clear, + the docs will additionally prefix the prompt with a + :term:`path` (showing what directory you are in) + whenever that is important. + + .. tabs:: + + .. group-tab:: bash + + .. code-block:: + + /odk-docs/ $ command is here - type this + Output is here. Don't type this. + + .. group-tab:: PowerShell + + .. code-block:: + + /odk-docs/ > command is here - type this + Output is here. Don't type this. -Then, create a directory called :file:`odk`. -This will contain your virtualenv and the docs repo as subdirectories. +#. Install git. -.. code-block:: console + Git is a version control system. + It helps us keep track of changes to the documentation. + (Similar to the undo history in a document editing program.) - $ mkdir odk - $ cd odk + .. tabs:: + + .. group-tab:: Linux -Now, inside that directory, create a python3 virtualenv. + Use your distribution's package management system + to `install git on Linux`_. -.. code-block:: console + .. _install git on Linux: https://git-scm.com/download/linux - $ virtualenv -p python3 odkenv + .. group-tab:: Mac -On Windows use: + .. rubric:: Option 1: Download an installer -.. code-block:: doscon + #. Download the `git installer for Mac`_. + #. Open the installer package. + #. Follow the prompts. + #. Accept any default settings. - > path\to\python\python -m venv odkenv + .. _git installer for Mac: https://git-scm.com/download/mac -The last part, ``odkenv``, is the name of virtual environment. -It can be whatever name you'd like to call it, -but we'll use ``odkenv`` throughout these docs. + .. rubric:: Option 2: Use Homebrew to install git + + .. code:: console -Activate your virtual environment with: + $ brew install git -.. code-block:: console + .. group-tab:: Windows - $ source odkenv/bin/activate + #. Download the `git installer for Windows`_. + #. Open the installer package. + #. Follow the prompts. + #. Accept any default settings. -On Windows use: + .. _git installer for Windows: https://git-scm.com/download/windows -.. code-block:: doscon +#. Install Git LFS - > odkenv\Scripts\activate + Git Large File Storage (Git LFS) is a tool that helps us + manage images, videos, and other files which are neither text nor code. + .. tabs:: -When you are done working, deactivate it with: + .. group-tab:: Linux -.. code-block:: console + Use your distribution's package management system + to `install Git LFS on Linux`_. - $ deactivate + .. _install Git LFS on Linux: https://github.com/git-lfs/git-lfs/wiki/Installation + After initial installation by the package manager, + complete the install by running: -.. _docs-gh-git: + .. code:: console -Github and git -~~~~~~~~~~~~~~~~~ + $ git lfs install -`Git`_ is a distributed version control system. -It makes it possible to track changes in files over time, -merge changes made by different contributors, -compare different versions of the same file, -and revert a file to an earlier point. + .. group-tab:: Mac -.. _git: https://git-scm.com/ + .. Option 1: Download an Installer -Git is complicated, -but you do not need to understand its advanced features or inner workings -to use it. + #. `Download Git LFS from the Git LFS website`_. + #. Open the downloaded installer. + #. Follow the prompts. + #. Accept any default settings. + #. Open the Terminal and add LFS to git: -`GitHub`_ is an online service -for hosting git repositories. -It also provides additional collaboration tools -like issue trackers and project boards. -Open Data Kit uses GitHub -for its public code and documentation projects. + .. code:: console -.. github: http://github.com + $ git lfs install -You will need to: + .. _Download Git LFS from the Git LFS website: https://git-lfs.github.com/ -1. `Install git `_ -2. Make sure that git is installed properly by typing (git) in the terminal or command prompt + .. rubric:: Option 2: Use Homebrew to install Git LFS. - - On Windows: If you get any errors, - check if your environment variables are set up correctly. - (See `this StackOverflow answer`__ for details.) + .. code:: console -3. Get a `GitHub`_ account. + $ brew install git-lfs + $ git lfs install -.. GitHub: https://github.com/ + .. group-tab:: Windows -__ https://stackoverflow.com/questions/26620312/installing-git-in-path-with-github-client-for-windows#answer-34767523 + #. `Download Git LFS from the Git LFS website`_. + #. Open the downloaded installer. + #. Follow the prompts. + #. Accept any default settings. + #. Open Powershell and add LFS to git: + .. code:: powershell -.. _glfs: + > git lfs install -GLFS -"""""" + .. _Download Git LFS from the Git LFS website: https://git-lfs.github.com/ -We use `Git Large File Storage (GLFS)`__ -to handle large binary files -like images and videos. -Once installed, -you normally won't need to do anything else. -GLFS is largely transparent when using git. +#. Install Python 3 -.. _GitLFS: https://git-lfs.github.com -__ GitLFS_ +`Python`_ is a programming language. +.. _Python: https://www.python.org/ -1. Install GLFS__. +Most of the ODK Docs tools are written in Python, +so you need it installed on your computer in order to use those tools. +(Don't worry. You don't need to know how to program in Python.) -__ GitLFS_ +We require Python 3 (`the current, supported version of the language`__), +and **strongly recommend** version 3.6 or later. -.. warning:: +.. __: https://wiki.python.org/moin/Python2orPython3 - **On Windows** +.. tabs:: - Make sure :file:`git-lfs.exe` and :file:`git.exe` are under the same main directory on Windows. (See `this page `_ for reference. + .. group-tab:: Linux -.. tip:: + Use your distribution's package management system + to `install Python 3.6+ on Linux`_. - **Debian Linux-based systems** + (For more help, + see `Installing Python on Linux`_.) - If the installation script on the GLFS website does not work correctly for your distribution, try installing it from the terminal using the package manager. + .. _install Python 3.6+ on Linux: https://docs.python-guide.org/starting/install3/linux/ + .. _Installing Python on Linux: https://realpython.com/installing-python/#linux - .. code-block:: console + .. group-tab:: Mac - $ sudo apt install git-lfs + .. tip:: -GLFS tracks binary files as defined in the :file:`.gitattributes` file `in the repo `_. Most common binary file formats are already listed, but there might be others we haven't thought of yet. + Mac OS includes a legacy (outdated) version of Python. + It's best to just ignore it. -.. _adding-new-glfs-formats: + .. rubric:: Option 1: Use the Python Installer for Mac -Adding new file formats to GLFS tracking -''''''''''''''''''''''''''''''''''''''''''''' + #. Download the latest `Python installer for Mac`_. -If you are adding binary files to the repo, -and they are in formats not already tracked, -**it is your responsibility to make sure they are tracked by GLFS.** + .. _mac-64-or-32: + .. admonition:: 64-bit or 32-bit? -To make sure they are properly tracked, -add them to the :file:`.gitattributes` file. + Python provides 64-bit and 32-bit installers. + You probably need the 64-bit installer. -.. code-block:: none + If you are running a relatively recent Mac OS update + (Mountain Lion or later — any Mac from the last several years) + the 64-bit installer is for you. - # file type section heading - *.{extension-to-track} filter=lfs diff=lfs merge=lfs -text + If you have an older Mac, + and are unsure if it can run a 64-bit installer, + `check the processor details`_ in :menuselection:` -> About This Mac`. -You can also use the command line. + .. _check the processor details: https://www.alesis.com/kb/article/1616#mac -.. code-block:: console + #. Open the Installer. + #. Follow the prompts. + #. Accept the default settings. + #. Open the Terminal to see if Python installed properly. - $ glfs track *.{file-extension} + .. code:: console -This will add a line to :file:`.gitattributes`. + $ python3 ---version + Python 3.7.0 -.. note:: + The output from :command:`python3 --version` might be a little different, + but it should be higher than ``3.6``. - Please keep :file:`.gitattributes` organized - by placing the new file format declaration - in the appropriate section, - or creating a new section as needed. + If you get an error here, something went wrong. + Try running the installer again. + If the problem persists, and you can't debug it yourself, + asks us about it on |odk-slack|_. -.. tip:: + .. _Python installer for Mac: https://www.python.org/downloads/mac-osx/ - If the command :command:`glfs` does not work, you may be using a version of GLFS that is organized as a git subcommand. In that case, substitute :command:`git lfs`. + .. rubric:: Option 2: Use Homebrew to install Python 3.6+ + .. code:: console + + $ brew install python + . + . + . + $ python3 --version + Python 3.7.0 -.. warning:: + The output from :command:`python3 --version` might be a little different, + but it should be higher than ``3.6``. - Updates to :file:`.gitattributes` must be done - in a commit before the commit - that adds the new binary files. + If you get an error here, something went wrong. + Try running :command:`brew install python` again. + If the problem persists, and you can't debug it yourself, + asks us about it on |odk-slack|_. - We will not accept pull requests - that include binary files untracked by GLFS. + .. group-tab:: Windows + #. Go to the `Python Releases for Windows`_ page. + #. Under the latest numbered release for Python 3, find and download the + :program:`Windows x86-64 web-based installer` (for a 64-bit system) + or the :program:`Windows x86 web-based installer` (for a 32-bit system). -.. _android-tools: + .. _win-64-or-32: + .. admonition:: 64-bit or 32-bit? -Android Tools -~~~~~~~~~~~~~~~~~ + Well over 90% of copmuters running Windows are 64-bit. + So you probably need the 64-bit version. -Some testing and documentation tasks -(including :ref:`making screenshots from ODK Collect `) -require the `Android Debug Bridge `_ command line tool. -You can either install Android Studio -or install ADB as a standalone SDK tool. + If you are running a very old or low-powered computer, + and you are unsure if it is 64-bit or 32-bit, + you can use `this guide from HP` (which will work for other computer brands) + to find that information. -.. _android-studio: + .. _this guide from HP: https://support.hp.com/us-en/document/c02002390 -Android Studio -"""""""""""""""""" + #. Open the downloaded installer. + #. Follow the prompts. + #. Accept all default settings. + #. Open Powershell and make sure the installation copmleted. -:abbr:`ADB (Android Debug Bridge)` is part of `Android Studio`_, -and is typically installed by default when you install Android Studio. + .. code:: powershell -.. _Android Studio: https://developer.android.com/studio/index.html + > python --version + Python 3.7.0 -This is the best way to get :command:`adb` -if you plan to do any other Android development. -To use it from the command line, -add the SDK Platform tools to your path. + The output from :command:`python --version` might be a little different, + but it should be whatever numbered version you downloaded. -On Mac, add the following to your :file:`.bash_profile` + If you get an error here, something went wrong. + Try running the installer again. + If the problem persists, and you can't debug it yourself, + asks us about it on |odk-slack|_. -.. code-block:: sh + .. _Python Releases for Windows: https://www.python.org/downloads/windows/ - export PATH=$PATH:~/Library/Android/sdk/tools/ +#. Set up your working directory + In whatever directory (folder) on your computer where you organize projects, + create a new directory for Open Data Kit, + and then navigate to that directory. + (We recommend calling this directory :file:`odk`, + and the rest of the guide will assume that's what you called it.) -.. note:: + .. tabs:: + + .. group-tab:: Bash + + $ mkdir odk + $ cd odk + /odk/ $ + + .. group-tab:: PowerShell + + > mkdir odk + > cd odk + /odk/ > + + For the rest of this guide, + we assume you are in the :file:`/odk/` directory, + or a subdirectory of it. + +#. Set up a virtual environment + + A `virtual environment` is a Python construct + that lets you download and install tools for a specific project + without installing them for your entire computer. + + .. _virtual environment: http://....... + + #. Create the virtual environment. + + .. tabs:: + + .. group-tab:: Bash + + .. code:: console + + /odk/ $ python3 -m venv odkenv + + .. group-tab:: PowerShell + + .. code:: powershell + + /odk/ > python-m venv odkenv + + #. Activate the virtual environment. + + .. tabs:: + + .. group-tab:: Bash + + .. code:: console + + /odk/ $ source odkenv/bin/activate + (odkenv) /odk/ $ + + .. group-tab:: PowerShell + + .. code:: console - On Windows, - you have to run Android Studio once - to complete the installation of ADB. - The tool can be found in - :file:`C:/Users/user-name/AppData/Local/Android/sdk/platform-tools`. - To add it to the environment variable path, - use the following command: + /odk/ > source odkenv/bin/activate + (odkenv) /odk/ > - .. code-block:: none + The ``(odkenv)`` 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. - set PATH=%PATH%;C:\Users\your user name\AppData\Local\Android\sdk\platform-tools + Later, to deactivate the virtual environment: + .. tabs:: + .. group-tab:: Bash + + .. code:: console -.. warning:: + (odkenv) /odk/ $ deactivate + /odk/ $ - The path specified above - assumes a default installation of Android Studio. - You may have installed Android Studio in a different location. + .. group-tab:: PowerShell + .. code:: console -.. _docs-workflow-setup: + (odkenv)/odk/ > deactivate + /odk/ > -Getting ready to work ------------------------ .. _fork-the-docs: +#. Fork the ODK Docs repository to your own GitHub account. + + A repository (repo) is a store of all the code and text for a project. + The `ODK Docs repo`_ is kept at GitHub. -Fork the docs -~~~~~~~~~~~~~~ + On GitHub, a "fork" is a copy of a repo, + cloned from one user to another. + In order to work on OFK Docs, + you will create your own fork. -Go to the `ODK Doc repo on GitHub`__ -and use the :guilabel:`Fork` button (top right) -to create your own copy. -After the process completes, -you'll be looking at your own fork on GitHub. + #. Go to the `ODK Doc repo`_ on GitHub. + #. Use the :guilabel:`Fork` button (top right) to create your own copy. + #. After the process completes, you'll be looking at your own fork on GitHub. -__ https://github.com/opendatakit/docs + .. _ODK Docs repo: https://github.com/opendatakit/docs .. _clone-the-docs: +#. Clone down your copy to your local computer -Clone to local -~~~~~~~~~~~~~~~~ + #. From your own fork of the repo on GitHub, select the :guilabel:`Clone or download` button. + #. Copy the URI from the text box that opens. + + It will be something like: + ``https://github.com/your-gh-username/docs.git`` -From your own fork of the repo on GitHub, -select the :guilabel:`Clone or download` button. -Copy the URI from the text box that opens. -It will be something like: -``https://github.com/your-gh-username/docs.git`` + #. Use your terminal to clone the repository. -Open your terminal -and `cd` to your preferred directory. -Then `git clone` the repo: + You should already be in the :file:`/odk` directory, + with the virtual environment active. -.. code-block:: console + .. tabs:: - $ git clone https://github.com/your-github-username/docs.git - . - . - . - $ cd docs + .. group-tabs:: Bash + + .. code:: console -The rest of the documentation assumes -you are in the directory for the repo -(the directory containing :file:`conf.py` and :file:`index.rst`). + (odkenv) /odk/ $ git clone https://github.com/your-github-username/docs.git + . + . + . + (odkenv) /odk/ $ cd docs + (odkenv) /odk/docs/ $ -.. tip:: + .. group-tabs:: Powershell + + .. code:: powershell + + (odkenv) /odk/ > git clone https://github.com/your-github-username/docs.git + . + . + . + (odkenv) /odk/ > cd docs + (odkenv) /odk/docs/ > + + .. warning:: + + Some of the git commands produce meaningless errors in PowerShell. + If you get an error when using git, but everything seems to work otherwise, + ignore the error. + + .. note:: + + This will cause your computer to download the entire ODK Docs repository, + including a large number of images. + It will take several minutes to complete. + + .. admonition:: Your local directory + + If you followed the instructions, + you should now have the following directory structure: + + - :file:`odk` + - :file:`docs` + - :file:`odkenv` - - The :command:`clone` command creates a new directory inside the current directory. - You do not need to create a new `odk-docs` directory first. - - As noted above, - we recommend a master :file:`odk` directory - that holds your virtualenv directory and your git repo - in two separate subdirectories. - So you would be in that master :file:`odk` directory - when you clone the repo. - - Double-check that the right folders are in the right places: + The :file:`odkenv` directory stores your virtual environment, + and you should not need to open it or directly view its content. + Just ignore it. - .. code-block:: none + The :file:`docs` directory is your copy of the ODK Docs repo. + You will do most of your work in this directory. - - odk/ - - odkenv/ - - docs/ + If you need to download or create additional files + which are not actually a part of the ODK Docs repository, + keep them out of the :file:`docs` directory. + + You can use the main :file:`odk` directory + for any other files you need to work on. + (For example, + you may want to create a directory called :file:`odk/forms` + to hold XLSForm and XForm files.) .. _upstream-the-docs: -Set the upstream remote -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#. Set the upstream remote + + In git, a :dfn:`remote` is a copy of a repo somewhere else. + From your local computer's point of view, + your online copy at GitHub is a remote. + + When you cloned down a repo, + your local copy gives your GitHub copy the name``origin``. -When you clone down a repo, -the local copy names your GitHub copy ``origin``. -You should also set ``upstream`` -as the name of the main ODK Docs GitHub repo. + You also need to give the primary ODK Docs repo a name, + and our convention is to name it ``upstream``. -.. code-block:: console + .. tabs:: - $ git remote add upstream https://github.com/opendatakit/docs.git + .. group-tab:: Bash -Or in Windows: + .. code:: console -.. code-block:: doscon + (odkenv) /odk/docs/ $ git remote add upstream https://github.com/opendatakit/docs.git + (odkenv) /odk/docs/ $ git remote -v + origin https://github.com/your-github-username/docs.git (fetch) + origin https://github.com/your-github-username/docs.git (push) + upstream https://github.com/opendatakit/docs.git (fetch) + upstream https://github.com/opendatakit/docs.git (push) - > git remote add upstream https://github.com/opendatakit/docs.git -Run ``git remote -v`` to check the status, you should see something like this: + .. group-tab:: PowerShell -.. code-block:: console + .. code:: powershell - $ origin https://github.com/your-github-username/docs.git (fetch) - $ origin https://github.com/your-github-username/docs.git (push) - $ upstream https://github.com/opendatakit/docs.git (fetch) - $ upstream https://github.com/opendatakit/docs.git (push) + (odkenv) /odk/docs/ > git remote add upstream https://github.com/opendatakit/docs.git + (odkenv) /odk/docs/ > git remote -v + origin https://github.com/your-github-username/docs.git (fetch) + origin https://github.com/your-github-username/docs.git (push) + upstream https://github.com/opendatakit/docs.git (fetch) + upstream https://github.com/opendatakit/docs.git (push) + + If everything went right, + you should see output similar to what is shown above. .. _install-doc-dependencies: -Install Dependencies -~~~~~~~~~~~~~~~~~~~~~~~ +#. Install Python tools with pip -The first time you clone down the repo, -you need to install the dependencies. -Make sure you have your Python 3 virtual environment -set up and activated, then: + Pip is a package management tool that comes with Python. + We use it to download and install our documentation tools. + These Python tools are listed in :file:`requirements.txt`. -.. code-block:: console + .. tabs:: - $ pip install -r requirements.txt + .. group-tab:: Bash -.. note:: + .. code:: console - If you are working on - the design, testing, or deployment of the docs, - you might need to install an additional PyPi package. - If so, - please update the :file:`requirements.txt` file with - :command:`pip freeze > requirements.txt`. - Pull requests which change :file:`requirements.txt` - should include a note about why the new package is needed. + (odkenv) /odk/docs/ $ pip install --upgrade pip + (odkenv) /odk/docs/ $ pip install -r requirements.txt -.. note:: + .. group-tab:: PowerShell + + .. code:: powershell + + (odkenv) /odk/docs/ > pip install --upgrade pip + (odkenv) /odk/docs/ > pip install -r requirements.txt + + The first command upgrades pip itself to the latest version. + Then second checks :file:`requirements.txt` and installs everything listed in it. + This will take several moments. + + .. note:: - If you have problems when running Sphinx commands (see below), - you may have a dependency issue. - Try running :command:`pip install -r requirements.txt` again. + If you are ever running one of the build commands shown below + and it fails with a message that includes ``ModuleNotFoundError``, + there might be changes to :file:`requirements.txt` + since you originally ran :command:`pip install -r requirement.txt`. + Run the installation again + and then retry your build. + +.. _choose-editor: + +#. Choose a text/code editor + + The documentation source files are written in a plain text format called `reStructuredText`_. + This means special formatting (bullets, headers, bold text) is represented by visible characters, + not hidden behind a graphical display. + When working on a documentation file, + you see and write something that looks like: + + .. code:: rst + + #. Choose a text/code editor + + The documentation source files + are written in a plain text format called `reStructuredText`_. + + You cannot write and edit these files + in a typical document preparation program like :program:`MS Word` or :program:`Google Docs`. + Instead, you need a coding editor. + + There are a lot of editors, + and people who use them often have very strong opinions about them. + You are free to choose any editor you like. + + If you've never used an editor before, + you might want to start with one of the easier and more popular ones: + + - `Atom `_ + - `Sublime `_ + - `VS Code `_ + - `Notebook++ `_ (Windows only) + + Most of these have plugins that will make writing reStructuredText easier + by color-coding the markup. + +This completes the setup of your local working environment. +Take a break before diving into how you actually work. .. _docs-workflow-details: -Workflow details +Working on the docs ------------------- +#. Find an issue to work on. + + Work on ODK Docs is planned using the GitHub repository's `issue tracker`_. + + #. Browse the `issue tracker`_ and find one you may want to work on. + #. Make sure you understand the goal of the project. + If goal isn't clear, ask. + If there is anything in the issue that doesn't make sense, + ask about it. + Feel free to make suggestions about how something could be accomplished. + #. If you decide to work on an issue, + assign yourself to it by writing **@opendatakit-bot claim** in a comment. + #. If the issue requires a novel or creative solution not defined in the issue already + (we've stated a problem and you think you know a way to fix it) + write a comment descibing your plan. + It is a good idea to get feedback on an idea before working on it. + Often, other contributors can provide additional context + about why a particular solution may or may not work. + + .. _issue tracker: https://github.com/opendatakit/docs/issues + + .. admonition:: Your first issue + + The very first issue you should work on as a new ODK Docs contributor is + `Issue 96 --- Line Edits`_. + The issue is very simple: + + 1. Find a typo. + 2. Fix the typo. + + This will help you get used to working with the documentation tools, + and helps us get rid of the inevitable errors that creep in to our writing. + + .. _Issue 96 --- Line Edits: https://github.com/opendatakit/docs/issues/96 + +.. add a link to a new Finding a Good Issue section/doc + +.. _check-at-master: + +#. Make sure you are on the master branch + + A branch is a named sequence of changes representing work on the repo. + For example, if you were going to work on `Issue 96 --- Line Edits`_, + you would create a new branch called ``line-edits`` to hold that work. + When you were done, + you would merge those changes back to the main branch, + which we call ``master``. + + The first time you clone the docs repo and start working, + you will be on the `master` branch. + + Each time you come back to starting work on a new issue, + make sure you are on the ``master`` branch before continuing. + + #. Check the current branch with :command:`git branch`. + This will output a list of branches, with a star next to the current one. + + .. tabs:: + + .. group-tab:: Bash + + .. code:: console + + (odkenv) /odk/docs/ $ git branch + branch-name + branch-name + branch-name + * master + branch-name + + .. group-tab:: PowerShell + + .. code:: powershell + + (odkenv) /odk/docs/ > git branch + branch-name + branch-name + branch-name + * master + branch-name + + #. If you are not on master, switch to master with :command:`git checkout`. + + .. tabs:: + + .. group-tab:: Bash + + .. code:: console + + (odkenv) /odk/docs/ $ git checkout master + Switched to branch 'master' + Your branch is up to date with 'origin/master'. + + .. group-tab:: PowerShell + + .. code:: powershell + + (odkenv) /odk/docs/ > git checkout master + Switched to branch 'master' + Your branch is up to date with 'origin/master'. + + .. _git-pull-the-docs: -Pull in changes from upstream -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#. Pull in changes from upstream -As other people make changes to the docs, -you need to keep your local copy up to date. + Other people are constantly making changes to the docs, + so you need to keep your local copy up to date. -You probably won't need to do this the first time, -but you should always pull in any changes from the main repository -before you begin working. + Before you start working, use :command:`git pull` + to pull in the changes from the upstream repository's master branch. + Then, just to be sure, you can use :command:`git status` + to make sure everything is up to date. + .. tabs:: -.. code-block:: console + .. group-tabs:: Bash - $ git pull upstream + .. code:: console -.. note:: + (odkenv) /odk/docs/ $ git pull upstream master + (odkenv) /odk/docs/ $ git status + On branch master + Your branch is up to date with 'origin/master'. - If you get this message: + nothing to commit, working tree clean - .. code-block:: none + .. group-tabs:: PowerShell - You asked to pull from the remote 'upstream', but did not specify a branch. - Because this is not the default configured remote for your current branch, - you must specify a branch on the command line. + .. code:: powershell + (odkenv) /odk/docs/ > git pull upstream master + (odkenv) /odk/docs/ > git status + On branch master + Your branch is up to date with 'origin/master'. - Try running ``git pull upstream master`` instead. + nothing to commit, working tree clean -.. _git-branch-the-docs: + .. warning:: -Make a New Branch -~~~~~~~~~~~~~~~~~~~ + Some git commands (including :command:`git pull` and :command:`git checkout`) + send error messages to PowerShell even when they work correctly. + If everything seems to be working, + you can ignore these. -Choose a specific, deliverable issue to work on. -This should be an `active issue from our issue tracker on GitHub`__. -__ https://github.com/opendatakit/docs/issues -Create a new branch in which to work on this specific issue. -Your branch name should briefly describe what you are doing. -For example, -the original author of this contributor guide -worked in a branch called ``contributing``. +.. _git-branch-the-docs: -Also, -make sure that all your branches are derived from ``master`` -to avoid confusing work from different commits. +#. Create a new branch for your work. -.. code-block:: console + .. tabs:: - $ git checkout -b branch-name + .. group-tab:: Bash -.. tip:: + .. code:: console + + (odkenv) /odk/docs/ $ git checkout -b branch-name + Switched to a new branch 'branch-name' + + .. group-tab:: PowerShell - Branch names should be short, lowercase, and use hyphens as separators. + .. code:: powershell + + (odkenv) /odk/docs/ > git checkout -b branch-name + Switched to a new branch 'branch-name' - Good branch names: + Branch names should be short, lowercase, and use hyphens as separators. + They do not need to carry a lot of information (like your name or the date). - - ``getting-started-guide`` - - ``contributing`` - - ``fix-issue-13`` + Good branch names: + + - ``getting-started-guide`` + - ``contributing`` + - ``fix-issue-13`` Bad branch names: - - ``getting started guide`` - - ``Getting started guide`` - - ``Getting_started_guide`` - - ``writing-the-getting-started-guide-adammichaelwood-july-2017-draft`` + - ``getting started guide`` + - ``Getting started guide`` + - ``Getting_started_guide`` + - ``writing-the-getting-started-guide-adammichaelwood-july-2017-draft`` .. _write-the-docs: -Work on the Docs -~~~~~~~~~~~~~~~~~~~ +#. Work on the documentation -Write and edit files in your favorite code editor. + 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: -.. note:: + :file:`odk1-src` + Files for the pages at http://docs.opendatakit.com + :file:`odk2-src` + Files for the pages at http://docs.opendatakit.com/odk2 + :file:`shared-src` + Files for pages shared by both ODK1 and ODK2 docs. + (This page the other contributor guide pages.) - You need to use a code editor to work on ODK docs. + If you're going to write or edit documentation text, please read: + + - :doc:`docs-syntax-guide` + - :doc:`docs-style-guide` - If you've never used a code editor before, - you should know that they are a little different - from other writing environments - like MS Word or your email editor. - - People have strong opinions about code editors, - and almost everyone has a favorite. - - If you're new to using an editor, - you might want to try `Atom`_ or `Sublime`_, - which are both popular and easy to use, - and they both have decent support for reStructuredText syntax. - - .. _Atom: https://atom.io/ - .. _Sublime: https://www.sublimetext.com/ + If you're working on code, please read: + + - :doc:`docs-developer-guide` -.. _spell-check: +#. Local checks -Spell check your work -~~~~~~~~~~~~~~~~~~~~~~ + Once you have worked on the documentation, + we want to make sure your contribution + will get accepted and published right away. -After making changes to the docs, -you need to run the spell checker. -To run the spell checker: + To ensure your changes will pass all the deployment tests, + you should run the tests locally first + and correct any problems. -.. code-block:: console + .. _spell-check: - $ sphinx-build -b spelling src build/spelling + #. Spell check -If there are any warnings, make sure that you fix them -to avoid a build failure. + If you've been working on files in :file:`odk1-src` or :file:`shared-src`: -The error messages will be displayed in the terminal -as well as stored in a file :file:`/build/spelling/output.txt`. + .. tabs:: -If you find a word which is not misspelled -and will have repeated use in docs, -add it to the spelling list -in the file :file:`/src/spelling_wordlist.txt`. + .. group-tabs:: Bash -If you find a word which is not misspelled -and is only required in a particular file, -use the :rst:dir:`spelling` directive -to list the words before the file content. + .. code:: console -.. code-block:: rst + (odkenv) /odk/docs/ $ make odk1-spell-check - .. spelling:: + .. group-tabs:: PowerShell - vN.N + .. code:: powershell - Upgrading Aggregate - ======================== + (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 -.. _style-test-docs: + If you've been working on files in :file:`odk2-src`: -Style-test your work -~~~~~~~~~~~~~~~~~~~~~ + .. tabs:: -After making changes to the docs, -you need to run the style-guide checks. -To run the style guide checks on all the docs: + .. group-tabs:: Bash -.. code-block:: console + .. code:: console + + (odkenv) /odk/docs/ $ make odk2-spell-check - $ python style-test.py + .. group-tabs:: PowerShell -To run the style guide checks on specified files: + .. code:: powershell -.. code-block:: console + (odkenv) /odk/docs/ > rm -r -fo tmp2-src + (odkenv) /odk/docs/ > rm -r -fo odk2-build + (odkenv) /odk/docs/ > Copy-Item odk2-src -Destination tmp2-src -Recurse + (odkenv) /odk/docs/ > Copy-Item shared-src -Destination tmp2-src -Recurse + (odkenv) /odk/docs/ > sphinx-build -b spelling tmp1-src odk2-build/spelling + (odkenv) /odk/docs/ > python util/check-spelling-output.py odk2-build - $ python style-test.py filename1.rst filename2.rst ... -If you want to run the style guide checks -on the files you modified, -use the option :option:`-d` or :option:`--diff`. + This will send some output to the terminal, + which will include mentions of any words not in the dictionary. -.. code-block:: console + - If the flagged words are really misspellings, correct them. - $ python style-test.py -d + - If the flagged words are not misspelled, and *should* be in the dictionary + add them to :file:`spelling_wordlist.txt`. -.. note:: + - If the flagged words are not misspelled, but *should not* be in the dictionary + (for example, they are non-words that make sense on a single page for a specific reason) + add them at the top of the file in which they are being used, + before the title heading: - This option checks only the files - that have been edited since the last :command:`git commit`. - So, if you modify the files, - make sure to check them - before making a commit. + .. code:: rst -To run the tests on modified files and other specified files: + .. spelling:: -.. code-block:: console + abc + def + exe + functool - $ python style-test.py -d filename1.rst filename2.rst ... + This Is The Page Title + ====================== -The output will consist of a list of warnings and errors. -Read through the warnings -and eliminate the ones that violate the style guide rules. + When adding new words to :file:`spelling_wordlist.txt` or the top of a document file, + please keep the words in alphabetical order. -.. note:: +.. style-test-docs +.. style testing individual files and diffs does not currently work - It is not necessary to fix all the warnings, - but you should review each warning - and decide if a change based on the warning makes sense. +.. _build-the-docs: -If there are any errors, you need to fix them to avoid build failure. -You can either fix the errors or -use the option :option:`-f` or :option:`--fix`. +#. Build and check -.. code-block:: console + We use a Python tool called Sphinx + to compile all the :file:`.rst` files into a working website. - $ python style-test.py -f + If you've been working on files in :file:`odk1-src` or :file:`shared-src`: -If you want to fix the errors in specified files: + .. tabs:: -.. code-block:: console + .. group-tab:: Bash - $ python style-test.py -f filename1.rst filename2.rst ... + Build the website: -.. tip:: + .. code:: console - After automatic error fixing, be sure to review the changes that were made. + (odkenv) /odk/docs/ $ make odk1 -To keep any part of a file from being checked, you can enclose the text in comments: + .. group-tab:: PowerShell -.. code-block:: rst + .. code:: powershell - .. startignore + (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 - Some text to ignore while testing. + If you've been working on files in :file:`odk2-src`: - .. endignore + .. tabs:: -You can also generate :file:`.csv` format output -using the :option:`-o` or :option:`--out_path` with the output filename: + .. group-tab:: Bash -.. code-block:: console + .. code:: console - $ python style-test.py -o output.csv + make odk2 -To generate output for specified files: + .. group-tab:: PowerShell -.. code-block:: console + .. code:: powershell - $ python style-test.py -o output.csv filename1.rst filename2.rst ... + (odkenv) /odk/docs/ > rm -r -fo tmp2-src + (odkenv) /odk/docs/ > rm -r -fo odk2-build + (odkenv) /odk/docs/ > Copy-Item odk2-src -Destination tmp2-src -Recurse + (odkenv) /odk/docs/ > Copy-Item shared-src -Destination tmp2-src -Recurse + (odkenv) /odk/docs/ > sphinx-build -b dirhtml tmp2-src odk2-build -.. note:: + This generates a lot of output. + Near the end of the output you may see a statement like: - Make sure to specify the output file before the input files - when you use the option :option:`-o`. + .. code:: none + + build succeeded, 18 warnings. -When you run the style guide checks, -style testing scripts are generated -before the test starts and are removed automatically -after the testing is complete. -If you want to keep these scripts for debugging, -use the option :option:`-s` or :option:`--store`: + Those warnings are problems with the text + which you need to fix before submitting your changes. + Scroll up in the terminal to find each warning, + so that you can address it in the source files. -.. code-block:: console + A Sphinx warning looks like this: - $ python style-test.py -s + .. code:: none -Use the option :option:`-h` or :option:`--help` -to get any help about style guide testing: + /path/to/file-name.rst:LINENUMBER: WARNING: warning message -.. code-block:: console + short excerpt from the file - $ python style-test.py -h + This tells you what file the problem is in, + the approximate line number, + and the nature of the problem. + Usually that is enough to fix it. + If you can not figure out the meaning of a particular warning, + you can always ask about it on the |odk-slack|_. -.. _build-the-docs: + .. note:: -Build, View, and Debug -~~~~~~~~~~~~~~~~~~~~~~~~ + Because of `a bug in Sphinx`_ + the line numbers in error and warning messages + will be off by about 15 lines + (the length of ``rst_prolog`` in :file:`conf.py`.). -To build the documentation into a viewable website: + .. _bug in Sphinx: https://github.com/sphinx-doc/sphinx/issues/2617 -.. code-block:: console + As you fix each warning, + run the build again to see if it disappears from the output. - $ sphinx-build -b dirhtml src build + .. note:: -This calls the sphinx-build utility. -The :option:`-b` switch specifies the builder, -which in this case is ``html``. -``src`` refers to the src directory which contains all :file:`.rst` files (the build source) -and ``build`` refers to the target of the build -(the built files will be put into a directory labeled :file:`build`). + The warning messages will refer to the file name + using the temporary directory path :file:`tmp1-src` or :file:`tmp2-src`. + You need to correct the problems in the real source directory + (:file:`odk1-src`, :file:`odk2-src`, or :file:`shared-src`). -When you run the build, -you may see error or warning messages. -These indicate potential problems with the documentation, such as: + .. admonition:: When you just can't fix the error... -- syntax errors -- broken links -- terms not included in the glossary + If you've done your best and asked on the |odk-slack|_, + and you still cannot correct the warning, + stop worrying about it and skip to the next step. + When you submit your changes on GitHub, + include a note about the warning. + Other contributors will help solve the problem before merging. -Error and warning messages -include a file name and line number to make it easy to locate them. -Try to resolve all your errors and warnings -before issuing a pull request. -If this is not possible, -please add a note in your pull request -so that we can help you debug the problem. -**We will not merge Pull Requests that have warnings or errors in them.** + Once you've corrected all the warnings that can be corrected... -.. note:: +#. Serve the documentation website locally and view it. - Because of `a bug in Sphinx`__ - the line numbers in error and warning messages - will be off by the length of `rst_prolog` in :file:`conf.py`. + If you've been working on files in :file:`odk1-src` or :file:`shared-src`: -__ https://github.com/sphinx-doc/sphinx/issues/2617 + .. tabs:: -To view the documentation in your web browser, -you can use Python's built-in web server. + .. group-tab:: Bash -.. code-block:: console + .. code:: console - $ cd build - $ python -m http.server 8000 + (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/) -Then open your browser and go to http://localhost:8000 + .. group-tab:: PowerShell -Read through your doc edits in the browser -and correct any issues in your source files. -You'll need to shut down the web server (:kbd:`CTRL C`) -before rebuilding, -then return to the main directory of the repo ( :command:`cd ..` ). + .. code:: powershell -It's a good idea to delete the ``build`` directory before each rebuild. + (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/) -.. code-block:: console + If you've been working on files in :file:`odk2-src`: - $ rm -rf build - $ sphinx-build -b dirhtml . build + .. tabs:: -.. tip:: + .. group-tab:: Bash - The script :file:`b.sh` automatically runs all the build commands. - It saves typing. - In the future, - it will also become the canonical build script for ODK Docs, - including additional tests and other build tasks. + .. code:: console -.. _build-pdf: + (odkenv) /odk/docs/ $ python -m http.server -d odk2-build 8000 + Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) -Build the Docs as a PDF -~~~~~~~~~~~~~~~~~~~~~~~ + .. group-tab:: PowerShell -To build the docs as a PDF, follow these steps: + .. code:: powershell -.. note:: + (odkenv) /odk/docs/ > python -m http.server -d odk2-build 8000 + Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) + + #. Open your browser and go to http://localhost:8000. + #. Read through your doc edits in the browser. + #. Go back to the source files to correct any errors you find. + #. Go to your terminal, and press :kbd:`CTRL C` to shut down the local web server. + #. Re-run the build and serve steps, continue proofreading. + + Once you are reasonably sure your changes are ready... + +#. Commit your changes to your local repository. + + A commit is snaphot of your working files in a particular state, + along with record of all the changes that led up to that state. + That snapshot is what you will submit to main repository. + + .. note:: + + We explain commit at this step because you need to do it before you can submit your changes. + However, you don't have to wait until you are done to commit. + You can commit as many times as you like while working. + + This can be especially helpful if you are working on a complicated set of changes, + over several working sessions. + + #. Stage the files for commit with :command:`git add`. - The steps below explain the build process for ODK 1's docs. To build the PDF for ODK 2's docs, replace **1** with **2** in the below commands. + To stage all changes for commit: -1. Install XeLatex + .. tabs:: - - For macOS, use `MacTex `_. - - For Windows, use `MiKTeX `_. - - For Ubuntu (or Debian), run + .. group-tab:: Bash - .. code-block:: console + .. code:: console - $ sudo apt-get install texlive-xetex + (odkenv) /odk/docs/ $ git add -A - .. note:: + .. group-tab:: PowerShell - Instead of installing XeLatex directly on your system, you can also use this `Docker image `_. + .. code:: powershell -2. Build LaTex file + (odkenv) /odk/docs/ # git add -A - .. code-block:: console +.. add link to staging subset of files - $ make odk1-latex + #. Commit the staged files with :command:`git commit`. -3. Generate PDF for the produced LaTex file + .. tabs:: - .. code-block:: console + .. group-tab:: Bash - $ make odk1-pdf + .. code:: console - The PDF will be generated in :file:`/odk1-build/_downloads/ODK-Documentation.pdf` + (odkenv) /odk/docs/ $ git commit -m "Write a commit message here." -.. _push-the-docs: + .. group-tab:: PowerShell -Push Your Branch -~~~~~~~~~~~~~~~~~~ + .. code:: powershell -Once your work on an issue is complete, -add the files you've changed or created, -and write a relevant commit message describing the changes. + (odkenv) /odk/docs/ # git commit -m "Write a commit message here." -.. code-block:: console + Your commit message needs to be wrapped in quote marks. + It should, in a sentence or less, explain your work. - $ git add my_changed_files - $ git commit -m "A small but relevant commit message" +#. Push your commited changes to your GitHub repo with :command:`git push`. -Then, push the changes. -The first time you do this, you need to specify the branch name: + .. tabs:: -.. code-block:: console + .. group-tab:: Bash - $ git push origin branch-name + .. code:: console -After that, you only need to use the :command:`push` command: + (odkenv) /odk/docs/ $ git push origin branch-name -.. code-block:: console + .. group-tab:: PowerShell - $ git push + .. code:: powershell + (odkenv) /odk/docs/ > git push origin branch-name -.. note:: ``origin`` is the local label for your GitHub fork. + .. warning:: + + The :command:`git push` command produces meaningless errors in PowerShell. + If you get an error when using :command:`git push`, + but everything seems to work otherwise, + ignore the error. + + .. tip:: + + You may be prompted to enter your GitHub username and password. + When entering your password, the curser won't move --- + it will look like you aren't entering anything, + even though you are. + (You can `store your GitHub credentials locally`_ + so you don't have to re-enter them every time.) + + .. _store your GitHub credentials locally: + https://help.github.com/articles/caching-your-github-password-in-git/ .. _pr-the-docs: -Issue a Pull Request -~~~~~~~~~~~~~~~~~~~~~~ - -A :dfn:`pull request` (or PR) -is a request from you to the ODK Docs maintainers -to pull in your changes to the main repo. - -Go to the `main docs repo on GitHub`__. -You'll see a message there referencing your recently pushed branches. Select :guilabel:`Compare & pull request` to start a pull request. - -__ https://github.com/opendatakit/docs> - -Follow GitHub's instructions. -The :guilabel:`Base fork` should be the main repo, -and :guilabel:`base` should be ``master``. -Your repo and working fork should be listed beside them. -(This information should populate by default, -but be sure to double check.) -If there is a green **Able to be merged** message, -you can proceed. - -You must include a PR comment. Things to include: - -- A summary of what you did. -- A note about anything that probably should have been done, - but you didn't do. -- A note about any new work this PR will create. -- The issue number you are working on. - If the PR completes the issue, - include the text ``Closes #`` and the issue number. -- A note about any errors or warnings, - and why you did not or could not resolve them. -- A note justifying any changes to :file:`requirements.txt`. -- A note about any difficulties, questions, or concerns - that came up while working on this issue. - -Complete the pull request. -The maintainers will review it as quickly as possible. -If there are any problems the maintainers can't deal with, -they will reach out to you. +#. Issue a pull request from your GitHub repo to the main ODK Docs repo. -.. note:: + A :dfn:`pull request` (or PR) + is a request from you to the ODK Docs maintainers + to pull in your changes to the main repo. + + #. Go to the `ODK Docs repo on GitHub`__. (Make sure you are logged in.) + #. Find the message near the top of the page that mentions your recent pushed branches. + Select :guilabel:`Compare & pull request` to start a pull request. + #. Follow GitHub's instructions to start the pull request. + + These details should fill-in automatically, + but be sure to double-check them: + + - :guilabel:`Base fork` should be the main repo (``opendatakit/docs``). + - :guilabel:`base` should be ``master``. + - Your repo and working branch name should be listed beside them. + + If there is a green **Able to be merged** message, you can proceed. + + #. Write a PR message explaining your work. + + The PR message field includes a template to remind you of what to include. + Fill in the template and delete any sections which are not applicable. + + A good PR message includes: + + - The issue number you are working on. + (Write ``closes #123`` if the PR completes the work for the issue. + If there's still work to do, write ``addresses #123``.) + - A summary of what you did. + - Details of work that still needs to be done. + - Details of new work created or implied by this PR. + - Details of any unresolved errors or warnings, + including detals of what you tried. + - Justification for any changes to :file:`requirements.txt`. + - Details of any difficulties, questions, or concerns + that came up while working on this issue. + + #. Submit your pull request. + + The maintainers and other contributors will review your PR as quickly as possible. + They may request changes to your work. + If changes are needed: + + #. Work on the files locally again. + (Use :command:`git branch` to make sure you are still in the same working branch.) + #. Stage (:command:`git add -A`) + and commit (:command:`git commit -m "Commit message"`) + your changes locally again. + #. Push your commit (:command:`git push origin branch-name`). + #. Your new commits will automatically update the PR. + Do not start a new PR. + + Once everything has been approved, + the changes will be merged in and will appear on :doc:`this website `. + At that point... congratulations! + You are now a contributor to Open Data Kit. + +.. _keep-working-the-docs: + +The next time you work +---------------------- + +We hope that contributing to ODK Docs is a rewarding experience +and that you'll want to keep going. +Each time you start work on a new issue +the process is the same as outline above. - If you rename a document file (:file:`*.rst`), - be sure that you add the redirect in your PR. +Here are a few things to keep in mind when you start your next contribution. - To add the redirect, go to :file:`s3_website.yml`, - and add a mapping from the old file name to the new file name - below the **redirects:** line, one mapping per line. - - If you have renamed :file:`old-name.rst` to :file:`new-name.rst`: +#. Return to ``master`` with :command:`git checkout`. - .. code-block:: yaml + New work is done on new branches which are started from master. + So, before you start a new branch, return to the master branch. - redirects: - old-name/index.html: new-name + .. tabs:: + + .. group-tab:: Bash - Notice the inclusion of ``/index.html`` on the left side. + .. code:: console + (odkenv) /odk/docs/ $ git checkout master -.. _keep-working-the-docs: + .. group-tab:: PowerShell + + .. code:: console + + (odkenv) /odk/docs/ > git checkout master + +#. Pull in changes with :command:`git pull`. + + You want to start your new work with + the latest version of everyone else's work. + + .. tabs:: -Keep Going -~~~~~~~~~~~ + .. group-tab:: Bash + + .. code:: console + + (odkenv) /odk/docs/ $ git pull upstream master + + .. group-tab:: PowerShell + + .. code:: console + + (odkenv) /odk/docs/ > git pull upstream master -Once the PR is merged, -you'll need to pull in the changes from the main repo ( ``upstream`` ) -into your local copy. +#. Update the master branch of your online GitHub repository. -.. code-block:: console + .. tabs:: + + .. group-tab:: Bash + + .. code:: console + + (odkenv) /odk/docs/ $ git push origin master + + .. group-tab:: PowerShell + + .. code:: console - $ git checkout master - $ git pull upstream master + (odkenv) /odk/docs/ > git push origin master -Then you should push those change to your copy on GitHub ( ``origin`` ). +#. Find a `new issue to work on`_. +#. Start a new branch for your work with :command:`git checkout -b branch-name`. -.. code-block:: console +.. _new issue to work on: https://github.com/opendatakit/docs/issues/ - $ git push +.. _keep-improving: -If you want, you can delete your previous branch. +Keep improving +-------------- -.. code-block:: console +As you are getting comfortable with the contribution process, +take a few minutes to read our :doc:`conributing-tips`. +You may also want to dig deeper into the +:doc:`docs-style-guide` and the :doc:`docs-syntax-guide`. +(And if you are writing code, +check out the :doc:`doc-developers-guide`.) - $ git branch -d branch-name +And don't forget to join us on the |odk-slack|_. -Now you can find a new issue to work on, -create a new branch, -and get to work again. +Open Data Kit is a community, +and we depend on each other's work. +Thank you for your contribution to ODK Docs +and your presence in this community. \ No newline at end of file diff --git a/shared-src/img/docs-tech-guide/terminal-icon.png b/shared-src/img/docs-tech-guide/terminal-icon.png new file mode 100644 index 000000000..1c51d5fc3 --- /dev/null +++ b/shared-src/img/docs-tech-guide/terminal-icon.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:03fc879c42ee0e021f5a9a2688361068a29840339d8676a2ab6200270ce625ea +size 7919 From 117eb2ce710cd312aa69e035843ab93a541fa954 Mon Sep 17 00:00:00 2001 From: Adam Michael Wood Date: Tue, 11 Sep 2018 18:22:31 -0700 Subject: [PATCH 5/6] fix all sphinx warnings --- shared-src/docs-tech-guide.rst | 89 ++++++++++++++++++---------------- 1 file changed, 48 insertions(+), 41 deletions(-) diff --git a/shared-src/docs-tech-guide.rst b/shared-src/docs-tech-guide.rst index ccc16e837..e29fc1b7c 100644 --- a/shared-src/docs-tech-guide.rst +++ b/shared-src/docs-tech-guide.rst @@ -5,8 +5,7 @@ Docs Technical Guide ========================== -This document explains how to contribute to -ODK Docs. +This document explains how to contribute to ODK Docs. .. note:: @@ -16,8 +15,7 @@ ODK Docs. are what the authors feel would be easiest for newcomers and those unfamiliar with open source. - You should feel free - to use your preferred tools. + You should feel free to use your preferred tools. .. _docs-before-you-begin: @@ -31,6 +29,8 @@ Learn a little about Open Data Kit Read about the project and the community at `Open Data Kit's website`_. +.. _Open Data Kit's website: http://opendatakit.org + .. _odk-accounts: Set up collaboration accounts @@ -61,6 +61,7 @@ and the :ref:`ODK Forum ` adding a picture.) .. _get-gh-account: + #. Set up a `GitHub`_ account. `GitHub`_ is a popular code storage and collaboration platform. @@ -75,6 +76,7 @@ and the :ref:`ODK Forum ` .. _GitHub: https://github.com/ .. _join-slack: + #. Join the `ODK Developer Slack`_. Slack is a popular chat platform. @@ -108,6 +110,7 @@ and the :ref:`ODK Forum ` adding a picture.) .. _join-forum: + #. Join the `ODK Forum`_ The `Open Data Kit Forum `_ is the main place for @@ -129,9 +132,8 @@ and the :ref:`ODK Forum ` .. _ODK Forum: http://forum.opendatakit.org .. _forum-or-slack-or-gh: -.. tip:: - .. rubric:: Should I ask in the Forum, the Slack, or a GitHub issue? +.. admonition:: Should I ask in the Forum, the Slack, or a GitHub issue? The ODK community talks a lot, in a lot of places. Sometimes it's hard to know where to ask a question. @@ -166,9 +168,8 @@ and the :ref:`ODK Forum ` - How do I add a specific feature to a form? - My ODK application crashed. - ------ - - But don't worry about posting a question in the wrong place. + .. rubric:: But don't worry about posting a question in the wrong place. + It is better to ask a question in the "wrong" venue than to not ask the question at all. Many of the same people are present in all three places, @@ -243,7 +244,7 @@ on any computer. .. rubric: Install Homebrew - `Homebrew`_ is a :term:`package manager` for Mac OS. + `Homebrew`_ is a package manager for Mac OS. It makes it easier to install other apps and tools from the command line. @@ -432,10 +433,7 @@ Most of the ODK Docs tools are written in Python, so you need it installed on your computer in order to use those tools. (Don't worry. You don't need to know how to program in Python.) -We require Python 3 (`the current, supported version of the language`__), -and **strongly recommend** version 3.6 or later. - -.. __: https://wiki.python.org/moin/Python2orPython3 +We require Python 3 and **strongly recommend** version 3.6 or later. .. tabs:: @@ -462,20 +460,21 @@ and **strongly recommend** version 3.6 or later. #. Download the latest `Python installer for Mac`_. .. _mac-64-or-32: + .. admonition:: 64-bit or 32-bit? - Python provides 64-bit and 32-bit installers. - You probably need the 64-bit installer. + Python provides 64-bit and 32-bit installers. + You probably need the 64-bit installer. - If you are running a relatively recent Mac OS update - (Mountain Lion or later — any Mac from the last several years) - the 64-bit installer is for you. + If you are running a relatively recent Mac OS update + (Mountain Lion or later — any Mac from the last several years) + the 64-bit installer is for you. - If you have an older Mac, - and are unsure if it can run a 64-bit installer, - `check the processor details`_ in :menuselection:` -> About This Mac`. + If you have an older Mac, + and are unsure if it can run a 64-bit installer, + `check the processor details`_ in :menuselection:` -> About This Mac`. - .. _check the processor details: https://www.alesis.com/kb/article/1616#mac + .. _check the processor details: https://www.alesis.com/kb/article/1616#mac #. Open the Installer. #. Follow the prompts. @@ -629,7 +628,7 @@ and **strongly recommend** version 3.6 or later. Later, to deactivate the virtual environment: - .. tabs:: + .. tabs:: .. group-tab:: Bash @@ -647,6 +646,7 @@ and **strongly recommend** version 3.6 or later. .. _fork-the-docs: + #. Fork the ODK Docs repository to your own GitHub account. A repository (repo) is a store of all the code and text for a project. @@ -657,13 +657,14 @@ and **strongly recommend** version 3.6 or later. In order to work on OFK Docs, you will create your own fork. - #. Go to the `ODK Doc repo`_ on GitHub. + #. Go to the `ODK Docs repo`_ on GitHub. #. Use the :guilabel:`Fork` button (top right) to create your own copy. #. After the process completes, you'll be looking at your own fork on GitHub. .. _ODK Docs repo: https://github.com/opendatakit/docs .. _clone-the-docs: + #. Clone down your copy to your local computer #. From your own fork of the repo on GitHub, select the :guilabel:`Clone or download` button. @@ -679,7 +680,7 @@ and **strongly recommend** version 3.6 or later. .. tabs:: - .. group-tabs:: Bash + .. group-tab:: Bash .. code:: console @@ -690,7 +691,7 @@ and **strongly recommend** version 3.6 or later. (odkenv) /odk/ $ cd docs (odkenv) /odk/docs/ $ - .. group-tabs:: Powershell + .. group-tab:: Powershell .. code:: powershell @@ -828,12 +829,14 @@ and **strongly recommend** version 3.6 or later. When working on a documentation file, you see and write something that looks like: + .. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html + .. code:: rst #. Choose a text/code editor - The documentation source files - are written in a plain text format called `reStructuredText`_. + The documentation source files + are written in a plain text format called `reStructuredText`_. You cannot write and edit these files in a typical document preparation program like :program:`MS Word` or :program:`Google Docs`. @@ -978,7 +981,7 @@ Working on the docs .. tabs:: - .. group-tabs:: Bash + .. group-tab:: Bash .. code:: console @@ -989,7 +992,7 @@ Working on the docs nothing to commit, working tree clean - .. group-tabs:: PowerShell + .. group-tab:: PowerShell .. code:: powershell @@ -1089,13 +1092,13 @@ Working on the docs .. tabs:: - .. group-tabs:: Bash + .. group-tab:: Bash .. code:: console (odkenv) /odk/docs/ $ make odk1-spell-check - .. group-tabs:: PowerShell + .. group-tab:: PowerShell .. code:: powershell @@ -1110,13 +1113,13 @@ Working on the docs .. tabs:: - .. group-tabs:: Bash + .. group-tab:: Bash .. code:: console (odkenv) /odk/docs/ $ make odk2-spell-check - .. group-tabs:: PowerShell + .. group-tab:: PowerShell .. code:: powershell @@ -1211,7 +1214,7 @@ Working on the docs This generates a lot of output. Near the end of the output you may see a statement like: - .. code:: none + .. code-block:: none build succeeded, 18 warnings. @@ -1222,7 +1225,7 @@ Working on the docs A Sphinx warning looks like this: - .. code:: none + .. code-block:: none /path/to/file-name.rst:LINENUMBER: WARNING: warning message @@ -1237,7 +1240,7 @@ Working on the docs .. note:: - Because of `a bug in Sphinx`_ + Because of a `bug in Sphinx`_ the line numbers in error and warning messages will be off by about 15 lines (the length of ``rst_prolog`` in :file:`conf.py`.). @@ -1409,7 +1412,11 @@ Working on the docs is a request from you to the ODK Docs maintainers to pull in your changes to the main repo. - #. Go to the `ODK Docs repo on GitHub`__. (Make sure you are logged in.) + #. Go to the `ODK Docs repo on GitHub`_. + (Make sure you are logged in.) + + .. _ODK Docs repo on GitHub: https://github.com/opendatakit/docs + #. Find the message near the top of the page that mentions your recent pushed branches. Select :guilabel:`Compare & pull request` to start a pull request. #. Follow GitHub's instructions to start the pull request. @@ -1539,11 +1546,11 @@ Keep improving -------------- As you are getting comfortable with the contribution process, -take a few minutes to read our :doc:`conributing-tips`. +take a few minutes to read our :doc:`contributing-tips`. You may also want to dig deeper into the :doc:`docs-style-guide` and the :doc:`docs-syntax-guide`. (And if you are writing code, -check out the :doc:`doc-developers-guide`.) +check out the :doc:`docs-developer-guide`.) And don't forget to join us on the |odk-slack|_. From ad623f22afd140fc8ecf2551da3bdabd639e9a8d Mon Sep 17 00:00:00 2001 From: Adam Michael Wood Date: Wed, 12 Sep 2018 10:31:00 -0700 Subject: [PATCH 6/6] fix all the broken stuff in contrib guide --- shared-src/docs-style-guide.rst | 2 +- shared-src/docs-tech-guide.rst | 453 +++++++++--------- .../img/docs-tech-guide/terminal-icon.png | 4 +- 3 files changed, 237 insertions(+), 222 deletions(-) diff --git a/shared-src/docs-style-guide.rst b/shared-src/docs-style-guide.rst index f80efd30b..adf4b8706 100644 --- a/shared-src/docs-style-guide.rst +++ b/shared-src/docs-style-guide.rst @@ -1,5 +1,5 @@ ***************** -Style Guide +Docs Style Guide ***************** .. _spelling-and-grammar: diff --git a/shared-src/docs-tech-guide.rst b/shared-src/docs-tech-guide.rst index e29fc1b7c..b61321dc6 100644 --- a/shared-src/docs-tech-guide.rst +++ b/shared-src/docs-tech-guide.rst @@ -2,20 +2,21 @@ src -Docs Technical Guide -========================== +Docs Contributor Technical Guide +================================= -This document explains how to contribute to ODK Docs. +This document explains how to set up your computer +and work locally as an ODK Docs contributor. +Local set up includes installing some software, +and working locally involves: -.. note:: +- writing documentation text or code in a code editor +- using the Terminal (the "Shell" or "Command Line") - Developer and authoring tools - have a lot of options and alternatives. - Local tools and workflows presented in this guide - are what the authors feel would be easiest - for newcomers and those unfamiliar with open source. - - You should feel free to use your preferred tools. +We encourage all potential contributors to try to work locally, +following this guide. +However, for small edits that only change a single file, +we have a :doc:`simpler online contribution process `. .. _docs-before-you-begin: @@ -60,10 +61,10 @@ and the :ref:`ODK Forum ` (But it is okay if you are unable or uncomfortable adding a picture.) -.. _get-gh-account: - #. Set up a `GitHub`_ account. + .. _get-gh-account: + `GitHub`_ is a popular code storage and collaboration platform. You will need a GitHub account to contribute to Open Date Kit documentation, or any other Open Date Kit projects. @@ -75,10 +76,10 @@ and the :ref:`ODK Forum ` .. _ODK Docs on GitHub: https://github.com/opendatakit/docs .. _GitHub: https://github.com/ -.. _join-slack: - #. Join the `ODK Developer Slack`_. + .. _join-slack: + Slack is a popular chat platform. The Open Data Kit contributor community uses Slack to discuss development, plan work, and generally keep in touch. @@ -95,24 +96,10 @@ and the :ref:`ODK Forum ` .. _ODK Developer Slack: http://slack.opendatakit.org/ - .. tip:: - - It is helpful (but not required) to use the same (or similar) username - on Slack that you use on :ref:`Github ` - and the :ref:`ODK Forum `. - - This makes it easy for other people to keep track of conversations - which sometimes span multiple online platforms. - - If you are willing and able to do so, - a profile picture is also very helpful. - (But it is okay if you are unable or uncomfortable - adding a picture.) - -.. _join-forum: - #. Join the `ODK Forum`_ + .. _join-forum: + The `Open Data Kit Forum `_ is the main place for support questions and conversations that affect the whole ODK community (users and other stake holders, as well as contributors). @@ -180,6 +167,16 @@ and the :ref:`ODK Forum ` Initial Setup ------------- +.. note:: + + Developer and authoring tools + have a lot of options and alternatives. + Local tools and workflows presented in this guide + are what the authors feel would be easiest + for newcomers and those unfamiliar with open source. + + You should feel free to use your preferred tools. + Before you begin working the first time you will need to install a few tools on your computer. @@ -193,7 +190,7 @@ on any computer. .. group-tab:: Windows - .. rubric:: Windows version prior to Windows 10 + .. rubric:: Windows versions prior to Windows 10 Use `Windows PowerShell`_. (Not the DOS Prompt.) @@ -242,16 +239,16 @@ on any computer. Follow the **Bash** or **Mac** instructions throughout the contributor guide. - .. rubric: Install Homebrew - - `Homebrew`_ is a package manager for Mac OS. - It makes it easier to install other apps and tools - from the command line. + .. admonition:: Optional: Install Homebrew - Follow the `installation instructions`_. - - .. _Homebrew: https://brew.sh/ - .. _installation instructions: Homebrew + `Homebrew`_ is a package manager for Mac OS. + It makes it easier to install other apps and tools + from the command line. + + Follow the `installation instructions`_. + + .. _Homebrew: https://brew.sh/ + .. _installation instructions: Homebrew .. group-tab:: Linux @@ -425,135 +422,135 @@ on any computer. #. Install Python 3 -`Python`_ is a programming language. + `Python`_ is a programming language. + + .. _Python: https://www.python.org/ -.. _Python: https://www.python.org/ + Most of the ODK Docs tools are written in Python, + so you need it installed on your computer in order to use those tools. + (Don't worry. You don't need to know how to program in Python.) -Most of the ODK Docs tools are written in Python, -so you need it installed on your computer in order to use those tools. -(Don't worry. You don't need to know how to program in Python.) + We require Python 3, version 3.6 or later. -We require Python 3 and **strongly recommend** version 3.6 or later. + .. tabs:: -.. tabs:: + .. group-tab:: Linux - .. group-tab:: Linux + Use your distribution's package management system + to `install Python 3.6+ on Linux`_. - Use your distribution's package management system - to `install Python 3.6+ on Linux`_. + (For more help, + see `Installing Python on Linux`_.) - (For more help, - see `Installing Python on Linux`_.) + .. _install Python 3.6+ on Linux: https://docs.python-guide.org/starting/install3/linux/ + .. _Installing Python on Linux: https://realpython.com/installing-python/#linux - .. _install Python 3.6+ on Linux: https://docs.python-guide.org/starting/install3/linux/ - .. _Installing Python on Linux: https://realpython.com/installing-python/#linux + .. group-tab:: Mac - .. group-tab:: Mac + .. tip:: - .. tip:: + Mac OS includes a legacy (outdated) version of Python. + It's best to just ignore it. - Mac OS includes a legacy (outdated) version of Python. - It's best to just ignore it. + .. rubric:: Option 1: Use the Python Installer for Mac - .. rubric:: Option 1: Use the Python Installer for Mac + #. Download the latest `Python installer for Mac`_. - #. Download the latest `Python installer for Mac`_. + .. _mac-64-or-32: - .. _mac-64-or-32: + .. admonition:: 64-bit or 32-bit? - .. admonition:: 64-bit or 32-bit? + Python provides 64-bit and 32-bit installers. + You probably need the 64-bit installer. - Python provides 64-bit and 32-bit installers. - You probably need the 64-bit installer. + If you are running a relatively recent Mac OS update + (Mountain Lion or later — any Mac from the last several years) + the 64-bit installer is for you. - If you are running a relatively recent Mac OS update - (Mountain Lion or later — any Mac from the last several years) - the 64-bit installer is for you. + If you have an older Mac, + and are unsure if it can run a 64-bit installer, + `check the processor details`_ in :menuselection:` -> About This Mac`. - If you have an older Mac, - and are unsure if it can run a 64-bit installer, - `check the processor details`_ in :menuselection:` -> About This Mac`. + .. _check the processor details: https://www.alesis.com/kb/article/1616#mac - .. _check the processor details: https://www.alesis.com/kb/article/1616#mac + #. Open the Installer. + #. Follow the prompts. + #. Accept the default settings. + #. Open the Terminal to see if Python installed properly. - #. Open the Installer. - #. Follow the prompts. - #. Accept the default settings. - #. Open the Terminal to see if Python installed properly. + .. code:: console - .. code:: console + $ python3 --version + Python 3.7.0 - $ python3 ---version + The output from :command:`python3 --version` might be a little different, + but it should be higher than ``3.6``. + + If you get an error here, something went wrong. + Try running the installer again. + If the problem persists, and you can't debug it yourself, + asks us about it on |odk-slack|_. + + .. _Python installer for Mac: https://www.python.org/downloads/mac-osx/ + + .. rubric:: Option 2: Use Homebrew to install Python 3.6+ + + .. code:: console + + $ brew install python + . + . + . + $ python3 --version Python 3.7.0 The output from :command:`python3 --version` might be a little different, but it should be higher than ``3.6``. If you get an error here, something went wrong. - Try running the installer again. + Try running :command:`brew install python` again. If the problem persists, and you can't debug it yourself, asks us about it on |odk-slack|_. - .. _Python installer for Mac: https://www.python.org/downloads/mac-osx/ - - .. rubric:: Option 2: Use Homebrew to install Python 3.6+ - - .. code:: console - - $ brew install python - . - . - . - $ python3 --version - Python 3.7.0 - - The output from :command:`python3 --version` might be a little different, - but it should be higher than ``3.6``. - - If you get an error here, something went wrong. - Try running :command:`brew install python` again. - If the problem persists, and you can't debug it yourself, - asks us about it on |odk-slack|_. - - .. group-tab:: Windows + .. group-tab:: Windows - #. Go to the `Python Releases for Windows`_ page. - #. Under the latest numbered release for Python 3, find and download the - :program:`Windows x86-64 web-based installer` (for a 64-bit system) - or the :program:`Windows x86 web-based installer` (for a 32-bit system). + #. Go to the `Python Releases for Windows`_ page. + #. Under the latest numbered release for Python 3, find and download the + :program:`Windows x86-64 web-based installer` (for a 64-bit system) + or the :program:`Windows x86 web-based installer` (for a 32-bit system). - .. _win-64-or-32: - .. admonition:: 64-bit or 32-bit? + .. _win-64-or-32: + .. admonition:: 64-bit or 32-bit? - Well over 90% of copmuters running Windows are 64-bit. - So you probably need the 64-bit version. + Well over 90% of copmuters running Windows are 64-bit. + So you probably need the 64-bit version. - If you are running a very old or low-powered computer, - and you are unsure if it is 64-bit or 32-bit, - you can use `this guide from HP` (which will work for other computer brands) - to find that information. + If you are running a very old or low-powered computer, + and you are unsure if it is 64-bit or 32-bit, + you can use `this guide from HP` (which will work for other computer brands) + to find that information. - .. _this guide from HP: https://support.hp.com/us-en/document/c02002390 + .. _this guide from HP: https://support.hp.com/us-en/document/c02002390 - #. Open the downloaded installer. - #. Follow the prompts. - #. Accept all default settings. - #. Open Powershell and make sure the installation copmleted. + #. Open the downloaded installer. + #. Follow the prompts. + #. Accept all default settings. + #. Open Powershell and make sure the installation completed. - .. code:: powershell + .. code:: powershell - > python --version - Python 3.7.0 + > python --version + Python 3.7.0 - The output from :command:`python --version` might be a little different, - but it should be whatever numbered version you downloaded. + The output from :command:`python --version` might be a little different, + but it should be whatever numbered version you downloaded. - If you get an error here, something went wrong. - Try running the installer again. - If the problem persists, and you can't debug it yourself, - asks us about it on |odk-slack|_. + If you get an error here, something went wrong. + Try running the installer again. + If the problem persists, and you can't debug it yourself, + asks us about it on |odk-slack|_. - .. _Python Releases for Windows: https://www.python.org/downloads/windows/ + .. _Python Releases for Windows: https://www.python.org/downloads/windows/ #. Set up your working directory @@ -567,15 +564,19 @@ We require Python 3 and **strongly recommend** version 3.6 or later. .. group-tab:: Bash - $ mkdir odk - $ cd odk - /odk/ $ + .. code:: console + + $ mkdir odk + $ cd odk + /odk/ $ .. group-tab:: PowerShell - > mkdir odk - > cd odk - /odk/ > + .. code:: powershell + + > mkdir odk + > cd odk + /odk/ > For the rest of this guide, we assume you are in the :file:`/odk/` directory, @@ -583,27 +584,27 @@ We require Python 3 and **strongly recommend** version 3.6 or later. #. Set up a virtual environment - A `virtual environment` is a Python construct + A `virtual environment`_ is a Python construct that lets you download and install tools for a specific project without installing them for your entire computer. - .. _virtual environment: http://....... + .. _virtual environment: https://docs.python.org/3/tutorial/venv.html #. Create the virtual environment. - .. tabs:: + .. tabs:: - .. group-tab:: Bash + .. group-tab:: Bash - .. code:: console + .. code:: console - /odk/ $ python3 -m venv odkenv + /odk/ $ python3 -m venv odkenv - .. group-tab:: PowerShell + .. group-tab:: PowerShell - .. code:: powershell + .. code:: powershell - /odk/ > python-m venv odkenv + /odk/ > python -m venv odkenv #. Activate the virtual environment. @@ -635,26 +636,26 @@ We require Python 3 and **strongly recommend** version 3.6 or later. .. code:: console (odkenv) /odk/ $ deactivate - /odk/ $ + /odk/ $ .. group-tab:: PowerShell .. code:: console - (odkenv)/odk/ > deactivate + (odkenv) /odk/ > deactivate /odk/ > -.. _fork-the-docs: - #. Fork the ODK Docs repository to your own GitHub account. - A repository (repo) is a store of all the code and text for a project. + .. _fork-the-docs: + + A :dfn:`repository` (:dfn:`repo`) is a store of all the code and text for a project. The `ODK Docs repo`_ is kept at GitHub. - On GitHub, a "fork" is a copy of a repo, + On GitHub, a :dfn:`fork` is a copy of a repo, cloned from one user to another. - In order to work on OFK Docs, + In order to work on ODK Docs, you will create your own fork. #. Go to the `ODK Docs repo`_ on GitHub. @@ -663,19 +664,18 @@ We require Python 3 and **strongly recommend** version 3.6 or later. .. _ODK Docs repo: https://github.com/opendatakit/docs -.. _clone-the-docs: - #. Clone down your copy to your local computer + .. _clone-the-docs: + #. From your own fork of the repo on GitHub, select the :guilabel:`Clone or download` button. #. Copy the URI from the text box that opens. - It will be something like: ``https://github.com/your-gh-username/docs.git`` #. Use your terminal to clone the repository. - You should already be in the :file:`/odk` directory, + You should already be in the :file:`odk` directory, with the virtual environment active. .. tabs:: @@ -720,6 +720,7 @@ We require Python 3 and **strongly recommend** version 3.6 or later. you should now have the following directory structure: - :file:`odk` + - :file:`docs` - :file:`odkenv` @@ -740,16 +741,16 @@ We require Python 3 and **strongly recommend** version 3.6 or later. you may want to create a directory called :file:`odk/forms` to hold XLSForm and XForm files.) -.. _upstream-the-docs: - #. Set the upstream remote + .. _upstream-the-docs: + In git, a :dfn:`remote` is a copy of a repo somewhere else. From your local computer's point of view, your online copy at GitHub is a remote. When you cloned down a repo, - your local copy gives your GitHub copy the name``origin``. + your local copy gives your GitHub copy the name ``origin``. You also need to give the primary ODK Docs repo a name, and our convention is to name it ``upstream``. @@ -782,14 +783,16 @@ We require Python 3 and **strongly recommend** version 3.6 or later. If everything went right, you should see output similar to what is shown above. -.. _install-doc-dependencies: - #. Install Python tools with pip - Pip is a package management tool that comes with Python. + .. _install-doc-dependencies: + + `Pip`_ is a package management tool that comes with Python. We use it to download and install our documentation tools. These Python tools are listed in :file:`requirements.txt`. + .. _Pip: https://pip.pypa.io/en/stable/user_guide/ + .. tabs:: .. group-tab:: Bash @@ -806,10 +809,12 @@ We require Python 3 and **strongly recommend** version 3.6 or later. (odkenv) /odk/docs/ > pip install --upgrade pip (odkenv) /odk/docs/ > pip install -r requirements.txt - The first command upgrades pip itself to the latest version. + The first command `upgrades pip`_ itself to the latest version. Then second checks :file:`requirements.txt` and installs everything listed in it. This will take several moments. + .. _upgrades pip: https://pip.pypa.io/en/stable/installing/#upgrading-pip + .. note:: If you are ever running one of the build commands shown below @@ -819,10 +824,10 @@ We require Python 3 and **strongly recommend** version 3.6 or later. Run the installation again and then retry your build. -.. _choose-editor: - #. Choose a text/code editor + .. _choose-editor: + The documentation source files are written in a plain text format called `reStructuredText`_. This means special formatting (bullets, headers, bold text) is represented by visible characters, not hidden behind a graphical display. @@ -838,6 +843,8 @@ We require Python 3 and **strongly recommend** version 3.6 or later. The documentation source files are written in a plain text format called `reStructuredText`_. + .. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html + You cannot write and edit these files in a typical document preparation program like :program:`MS Word` or :program:`Google Docs`. Instead, you need a coding editor. @@ -871,15 +878,14 @@ Working on the docs #. Browse the `issue tracker`_ and find one you may want to work on. #. Make sure you understand the goal of the project. - If goal isn't clear, ask. - If there is anything in the issue that doesn't make sense, - ask about it. + If the goal isn't clear, ask. + If there is anything in the issue that doesn't make sense, ask about it. Feel free to make suggestions about how something could be accomplished. #. If you decide to work on an issue, assign yourself to it by writing **@opendatakit-bot claim** in a comment. #. If the issue requires a novel or creative solution not defined in the issue already (we've stated a problem and you think you know a way to fix it) - write a comment descibing your plan. + write a comment describing your plan. It is a good idea to get feedback on an idea before working on it. Often, other contributors can provide additional context about why a particular solution may or may not work. @@ -900,12 +906,10 @@ Working on the docs .. _Issue 96 --- Line Edits: https://github.com/opendatakit/docs/issues/96 -.. add a link to a new Finding a Good Issue section/doc - -.. _check-at-master: - #. Make sure you are on the master branch + .. _check-at-master: + A branch is a named sequence of changes representing work on the repo. For example, if you were going to work on `Issue 96 --- Line Edits`_, you would create a new branch called ``line-edits`` to hold that work. @@ -966,11 +970,10 @@ Working on the docs Switched to branch 'master' Your branch is up to date with 'origin/master'. - -.. _git-pull-the-docs: - #. Pull in changes from upstream + .. _git-pull-the-docs: + Other people are constantly making changes to the docs, so you need to keep your local copy up to date. @@ -1010,12 +1013,10 @@ Working on the docs If everything seems to be working, you can ignore these. - - -.. _git-branch-the-docs: - #. Create a new branch for your work. + .. _git-branch-the-docs: + .. tabs:: .. group-tab:: Bash @@ -1041,17 +1042,17 @@ Working on the docs - ``contributing`` - ``fix-issue-13`` - Bad branch names: + Bad branch names: - ``getting started guide`` - ``Getting started guide`` - ``Getting_started_guide`` - ``writing-the-getting-started-guide-adammichaelwood-july-2017-draft`` -.. _write-the-docs: - #. Work on the documentation + .. _write-the-docs: + Finally, you can open an :ref:`editor of your choice ` and work on the documentation. @@ -1063,18 +1064,20 @@ Working on the docs Files for the pages at http://docs.opendatakit.com/odk2 :file:`shared-src` Files for pages shared by both ODK1 and ODK2 docs. - (This page the other contributor guide pages.) + (This page and the other contributor guide pages.) If you're going to write or edit documentation text, please read: - :doc:`docs-syntax-guide` - :doc:`docs-style-guide` - If you're working on code, please read: + If you're working on code or deployment, please read: - :doc:`docs-developer-guide` -#. Local checks +#. Local checks + + .. _test-the-docs: Once you have worked on the documentation, we want to make sure your contribution @@ -1084,10 +1087,10 @@ Working on the docs you should run the tests locally first and correct any problems. - .. _spell-check: - #. Spell check + .. _spell-check: + If you've been working on files in :file:`odk1-src` or :file:`shared-src`: .. tabs:: @@ -1159,24 +1162,23 @@ Working on the docs When adding new words to :file:`spelling_wordlist.txt` or the top of a document file, please keep the words in alphabetical order. -.. style-test-docs -.. style testing individual files and diffs does not currently work - -.. _build-the-docs: + #. Style check #. Build and check - We use a Python tool called Sphinx + .. _build-the-docs: + + We use a Python tool called `Sphinx`_ to compile all the :file:`.rst` files into a working website. + .. _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 - Build the website: - .. code:: console (odkenv) /odk/docs/ $ make odk1 @@ -1243,7 +1245,7 @@ Working on the docs Because of a `bug in Sphinx`_ the line numbers in error and warning messages will be off by about 15 lines - (the length of ``rst_prolog`` in :file:`conf.py`.). + (the length of ``rst_prolog`` in :file:`conf.py`). .. _bug in Sphinx: https://github.com/sphinx-doc/sphinx/issues/2617 @@ -1266,11 +1268,12 @@ Working on the docs include a note about the warning. Other contributors will help solve the problem before merging. - Once you've corrected all the warnings that can be corrected... #. Serve the documentation website locally and view it. + .. _serve-the-docs-locally: + If you've been working on files in :file:`odk1-src` or :file:`shared-src`: .. tabs:: @@ -1311,19 +1314,23 @@ Working on the docs #. Read through your doc edits in the browser. #. Go back to the source files to correct any errors you find. #. Go to your terminal, and press :kbd:`CTRL C` to shut down the local web server. - #. Re-run the build and serve steps, continue proofreading. + #. Re-run the build and serve steps. + #. Continue proofreading. Once you are reasonably sure your changes are ready... #. Commit your changes to your local repository. - A commit is snaphot of your working files in a particular state, - along with record of all the changes that led up to that state. - That snapshot is what you will submit to main repository. + .. _commit-the-docs: + + A :dfn:`commit` is snaphot of your working files in a particular state, + along with a record of all the changes that led up to that state. + That snapshot is what you will submit to the main repository. .. note:: - We explain commit at this step because you need to do it before you can submit your changes. + We explain how to do a commit at this step + because you need to do it before you can submit your changes. However, you don't have to wait until you are done to commit. You can commit as many times as you like while working. @@ -1346,9 +1353,7 @@ Working on the docs .. code:: powershell - (odkenv) /odk/docs/ # git add -A - -.. add link to staging subset of files + (odkenv) /odk/docs/ > git add -A #. Commit the staged files with :command:`git commit`. @@ -1364,13 +1369,15 @@ Working on the docs .. code:: powershell - (odkenv) /odk/docs/ # git commit -m "Write a commit message here." + (odkenv) /odk/docs/ > git commit -m "Write a commit message here." Your commit message needs to be wrapped in quote marks. It should, in a sentence or less, explain your work. #. Push your commited changes to your GitHub repo with :command:`git push`. + .. _push-the-docs: + .. tabs:: .. group-tab:: Bash @@ -1398,16 +1405,17 @@ Working on the docs When entering your password, the curser won't move --- it will look like you aren't entering anything, even though you are. - (You can `store your GitHub credentials locally`_ - so you don't have to re-enter them every time.) + + To avoid having to retype these every time, + you can `store your GitHub credentials locally`_. .. _store your GitHub credentials locally: https://help.github.com/articles/caching-your-github-password-in-git/ -.. _pr-the-docs: - #. Issue a pull request from your GitHub repo to the main ODK Docs repo. + .. _pr-the-docs: + A :dfn:`pull request` (or PR) is a request from you to the ODK Docs maintainers to pull in your changes to the main repo. @@ -1428,7 +1436,11 @@ Working on the docs - :guilabel:`base` should be ``master``. - Your repo and working branch name should be listed beside them. - If there is a green **Able to be merged** message, you can proceed. + You will see either a green **Able to be merged** message + or a message informing that the branch can not be merged. + You can proceed in either case. + If the branch cannot be merged, + the maintainers will work with you to resolve the problem. #. Write a PR message explaining your work. @@ -1444,7 +1456,7 @@ Working on the docs - Details of work that still needs to be done. - Details of new work created or implied by this PR. - Details of any unresolved errors or warnings, - including detals of what you tried. + including details of what you tried. - Justification for any changes to :file:`requirements.txt`. - Details of any difficulties, questions, or concerns that came up while working on this issue. @@ -1455,12 +1467,15 @@ Working on the docs They may request changes to your work. If changes are needed: - #. Work on the files locally again. + #. **Don't worry.** + Revision is a normal part of technical writing, + and everyone (even the project's founders and leaders) + has their work reviewed and are frequently asked to revise it. + #. Work on the files again locally. (Use :command:`git branch` to make sure you are still in the same working branch.) - #. Stage (:command:`git add -A`) - and commit (:command:`git commit -m "Commit message"`) - your changes locally again. - #. Push your commit (:command:`git push origin branch-name`). + #. :ref:`Stage and commit ` your changes locally again + (:command:`git add -A`; :command:`git commit -m "Commit message"`). + #. :ref:`Push your commit ` (:command:`git push origin branch-name`). #. Your new commits will automatically update the PR. Do not start a new PR. @@ -1481,7 +1496,7 @@ the process is the same as outline above. Here are a few things to keep in mind when you start your next contribution. -#. Return to ``master`` with :command:`git checkout`. +#. Return to ``master`` with :command:`git checkout master`. New work is done on new branches which are started from master. So, before you start a new branch, return to the master branch. @@ -1500,9 +1515,9 @@ Here are a few things to keep in mind when you start your next contribution. (odkenv) /odk/docs/ > git checkout master -#. Pull in changes with :command:`git pull`. +#. Pull in changes with :command:`git pull upstream master`. - You want to start your new work with + You need to start your new work from the latest version of everyone else's work. .. tabs:: @@ -1536,7 +1551,7 @@ Here are a few things to keep in mind when you start your next contribution. (odkenv) /odk/docs/ > git push origin master #. Find a `new issue to work on`_. -#. Start a new branch for your work with :command:`git checkout -b branch-name`. +#. `Start a new branch for your work `_ with :command:`git checkout -b branch-name`. .. _new issue to work on: https://github.com/opendatakit/docs/issues/ diff --git a/shared-src/img/docs-tech-guide/terminal-icon.png b/shared-src/img/docs-tech-guide/terminal-icon.png index 1c51d5fc3..1614755d1 100644 --- a/shared-src/img/docs-tech-guide/terminal-icon.png +++ b/shared-src/img/docs-tech-guide/terminal-icon.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:03fc879c42ee0e021f5a9a2688361068a29840339d8676a2ab6200270ce625ea -size 7919 +oid sha256:7dfefef2c64894c7f5971ff8838c64ca3cd1df921481cd4e442804638093ada3 +size 7637