Merge branch 'main' into rajk/03-July-relnotes

README.md

@@ -10,27 +10,47 @@
 
 Welcome to Bittensor Developer Docs. These docs are built using [Docusaurus](https://docusaurus.io/). See the below instructions to build these docs locally.
 
+## Basic
+
+In most cases you only need to follow this basic approach. If you know what you are doing, also see the below [Advanced](#advanced) section.
+
 ### Installation
 
 ```
-$ yarn
+git clone https://github.com/opentensor/developer-docs.git
 ```
 
-### Local Development
+```
+cd developer-docs
+```
 
 ```
-$ yarn start
+yarn
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+The above steps will install Docusaurus and all its dependencies on your local machine.
 
-### Build
+### Start a preview server
+
+From the `developer-docs` directory run this command:
 
 ```
-$ yarn build
+yarn start
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+The above command starts a local Docusaurus development server and opens up a browser window. Any changes you make within the `developer-docs` directory will be shown live in the browser window. You do not need to restart the server. Simply refresh the browser.
+
+Follow the [WRITING STYLE GUIDE](./WRITING-STYLE-GUIDE.md) and stick to those writing style guidelines to make your contribution to these docs better.
+
+## Advanced
+
+### Build static html
+
+```
+yarn build
+```
+
+This command generates static content, including all the static html files and assets, into the `build` directory. You can then serve this `build` directory using any static hosting service.
 
 ### Deployment
 
@@ -47,3 +67,5 @@ $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+---

WRITING-STYLE-GUIDE.md

@@ -0,0 +1,149 @@
+<h1 align="center">
+  <a href="https://www.docs.bittensor.com">
+    <img alt="Tao Logo" src="./static/img/tao-logo.png" />
+  </a>
+</h1>
+<h2 align="center">Writing Style Guide</h2>
+
+-----------------------------------------------------------------------------
+
+When you write a developer document for Opentensor Foundation, your audience should find your documentation readable, informative, and concise. To accomplish these goals, here below are a few helpful writing style recommendations. We encourage you to stick to the writing style described on this page.
+
+# General principles
+
+## Style and tone
+
+- Avoid colloquialisms and jargon.
+
+- Address the user directly. Use "you" instead of "user" or "they".
+
+- Use the active voice. Use present tense.
+
+- Avoid writing the way you speak. That is, avoid using contractions (aren’t, don’t, isn’t), jokes or using colloquial content.
+
+## Readability
+
+- Break up walls of text (long passages of text) into smaller chunks to aid readability. Use lists.
+
+- Provide context. Your readers can be beginner developers or experts in specialized fields. They may not know what you are talking about without a context.
+
+- Use shorter sentences (**26 words or less**). They are easier to understand (and easier to translate).
+
+- Define acronyms and abbreviations on the first usage in every topic.
+
+- Our documentation is written in US English, but the audience will include people for whom English is not their primary language. 
+
+- Avoid culturally specific references, humor, names.
+
+- Avoid compound verbs. Try to substitute a simpler verb.
+
+- Write dates and times in unambiguous and clear ways. Write "27 November 2020" instead of either "11/27/2020" or "27/11/2020" or "November 27, 2020".
+
+- Avoid negative sentence construction. Try not to say "it is not uncommon" but instead say "it is common". Yes there is a subtle difference between the two but for technical writing this simplification works better.
+
+- Avoid directional language (below, left) in procedural documentation (like a step by step instruction section), wherever possible. Instead refer to the actual step number.
+
+- Be consistent in capitalization and punctuation.
+
+- Avoid hypothetical future "would". Instead, write in the present tense. 
+  - **For example**: Avoid saying "The compiler would then send" but instead say, "The compiler sends".
+
+- Avoid the`&` character in the descriptive text. Use the word "and".
+
+## Avoid foreshadowing
+
+- Do not refer to future features or products. 
+
+- Avoid making excessive or unsupported claims about future enhancements.
+
+## Titles and headings
+
+Document titles and section headings should either:
+
+- Explicitly state the purpose of the section.
+
+- Be a call to action, or intention.
+
+This approach makes it easier for the reader to get her specific development task done.
+
+### Examples
+
+- **Preferred**: Sharding your data (section heading)
+  **Avoid**: Data sharding fundamentals (title is not purpose-driven)
+
+- **Preferred**: Creating input pipelines
+  **Avoid**: Input pipelines
+
+## Rules
+
+- Document titles (**h1**): Use title case. 
+  - **For example**: "Running a Model".
+
+- Section headings within a document (**h2, h3, h4, h5**): Use sentence case. 
+  - **For example**: "Running a model".
+
+- A document title is the main title of a document page. A document has only one document title. 
+  - **Example**: "Writing Style Guide" at the beginning of this page is a document title. The document title also appears at the top level in the navigation bar, so it must be short, preferably four to five words or less.
+
+- A section heading is the title for an individual section within a document page. 
+  - **Example**: "Titles and headings" up above this section. A document page can have multiple sections, and hence multiple section headings.
+
+- Use a heading hierarchy. Do not skip levels of the heading hierarchy. 
+  - **For example**, put h3 only under h2.
+
+- To change the visual formatting of a heading, use CSS instead of using a heading level that does not fit the hierarchy.
+
+- Do not write empty headings or headings with no associated content.
+
+- Avoid using question marks in document titles and section headings.
+  - **Example**:
+    - **Avoid**: How it works?
+    - **Preferred**: How it works
+
+- Avoid using emphasis or italics in document titles or section headings.
+
+- Avoid joining words using a slash.
+  - **Example:**
+    - **Avoid**: Execute on your CPU/GPU system
+    - **Preferred**: Execute on your CPU or GPU system
+
+## Python docstrings
+
+We use the [Napoleon extension](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/) with Sphinx for generating API docs.
+
+### Recommendation
+
+- Use the [Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google) docstrings for Python.
+
+### Example
+
+**Follow**:
+
+```
+Args:
+
+    path (str): The path of the file to wrap
+    field_storage (FileStorage): The :class:\`FileStorage\` instance to wrap
+    temporary (bool): Whether or not to delete the file when the File instance is destructed
+
+Returns:
+
+    BufferedFileStorage: A buffered writable file descriptor
+
+```
+
+**Avoid**:
+
+```
+:param path: The path of the file to wrap
+:type path: str
+:param field_storage: The :class:\`FileStorage\` instance to wrap
+:type field_storage: FileStorage
+:param temporary: Whether or not to delete the file when the File instance is destructed
+:type temporary: bool
+:returns: A buffered writable file descriptor
+:rtype: BufferedFileStorage
+
+```
+
+---

docs/getting-started/installation.md

@@ -14,88 +14,51 @@ If you already installed Bittensor, make sure you upgrade to the latest version.
 python3 -m pip install --upgrade bittensor
 ```
 
-or
-```bash
-python -m pip install --upgrade bittensor
-```
-
 ## Install on macOS and Linux
 
-:::tip For macOS on Apple silicon
-For Apple Silicon see the below [Installing on Apple Silicon](#installing-on-apple-silicon) section. 
-:::
-
 You can install Bittensor on your local machine in either of the following ways. **Make sure you verify your installation after you install**:
-- Using a Bash command.
-- Using `pip3 install`.
-- From source.
+- [Install using a Bash command](#install-using-a-bash-command).
+- [Install using `pip3 install`](#install-using-pip3-install)
+- [Install from source](#install-from-source)
 
-### Using a Bash command
+### Install using a Bash command
 
 This is the most straightforward method. It is recommended for a beginner as it will pre-install requirements like Python, if they are not already present on your machine. Copy and paste the following `bash` command into your terminal:
 
 ```bash
 /bin/bash -c "$(curl -fsSL https://github.com/raw/opentensor/bittensor/master/scripts/install.sh)"
 ```
 
-### Using `pip3 install`
+### Install using `pip3 install`
 
 ```bash
 pip3 install bittensor
 ```
 
-### From source
-
-1. Clone the Bittensor repo.
-
-    ```bash
-    git clone https://github.com/opentensor/bittensor.git
-    ```
-2. Install with `python3`
-
-    ```bash
-    python3 -m pip install -e bittensor/
-    ```
+### Install from source
+1. Create and activate a virtual environment
 
-### Installing on Apple Silicon
+    - Create Python virtual environment. Follow [this guide on python.org](https://docs.python.org/3/library/venv.html#creating-virtual-environments).
 
-To install Bittensor on Apple M1 or M2, we recommend you first activate a Python virtual environment. Follow the below steps:
+    - Activate the new environment. Follow [this guide on python.org](https://docs.python.org/3/library/venv.html#how-venvs-work)
 
-#### Activate a virtual environment
+2. Clone the Bittensor repo
 
-1. Install `conda` on macOS. Follow [this guide on conda.io](https://conda.io/projects/conda/en/latest/user-guide/install/macos.html).
-2. Download the `apple_m1_environment.yml` configuration file from Bittensor. 
-   - [Click to visit the file](https://github.com/opentensor/bittensor/blob/master/scripts/environments/apple_m1_environment.yml).
-   - Click on the `Raw` button at the top right and save the raw file on your local machine.
-
-3. Create the `conda` environment using the `apple_m1_environment.yml` file you just downloaded:
-    ```bash
-    conda env create -f apple_m1_environment.yml
-    ```
-
-4. Activate the new environment: 
-   ```bash
-   conda activate bittensor
-   ```
+```bash
+git clone https://github.com/opentensor/bittensor.git
+```
+3.  Change to the Bittensor directory:
 
-5. Install `shtab`:
-   ```bash
-   conda install -c anaconda shtab
-   ```
-
-6. Verify that the new environment was installed correctly:
-
-   ```bash
-   conda env list
-   ```
-7. Next, install Bittensor as shown below.
+```bash
+cd bittensor
+```
 
-#### Install Bittensor
+4. Install Bittensor
 
 Run the below command to install Bittensor in the above virtual environment.
 
 ```python
-pip3 install bittensor --no-deps
+pip install .
 ```
 
 ## Install on Windows
@@ -124,9 +87,7 @@ which will give you the below output:
 
 ```text
 usage: btcli <command> <command args>
-
 bittensor cli <version number>
-
 positional arguments:
 ...
 ```
@@ -141,7 +102,7 @@ You will see the version number you installed in place of `<version number>`.
     ```
 2. Enter the following two lines in the Python interpreter.
 
-   ```python
+    ```python
     import bittensor as bt
     print( bt.__version__ )
     ```
@@ -160,9 +121,9 @@ You will see the version number you installed in place of `<version number>`.
 You can also verify the Bittensor installation by listing the axon information for the neurons. Enter the following lines in the Python interpreter.
 
 ```python
->>> import bittensor as bt
->>> metagraph = bt.metagraph(1)
->>> metagraph.axons[:10]
+import bittensor as bt
+metagraph = bt.metagraph(1)
+metagraph.axons[:10]
 ```
 The Python interpreter output will look like below.