gleitz · JohnDaWalka · Mar 27, 2025
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,26 @@
+# Documentation Overview
+
+This document provides an overview of the documentation structure for the `howdoi` project. The documentation is organized into several subdirectories, each containing markdown files related to specific topics.
+
+## Documentation Structure
+
+- `contributing/`
+  - `contributing.md`: Contains guidelines for contributing to the project, including code contributions and documentation improvements.
+- `setup/`
+  - `development_env.md`: Instructions for setting up the development environment.
+  - `windows-contributing.md`: Instructions for setting up the development environment on Windows.
+- `getting_started/`
+  - `usage.md`: Basic usage instructions for the `howdoi` command-line tool.
+- `advanced/`
+  - `howdoi_advanced_usage.md`: Advanced usage instructions and features of the `howdoi` tool.
+
+## Navigating the Documentation
+
+To navigate the documentation, start by exploring the `index.md` file, which serves as the homepage for the documentation site. From there, you can access various sections and subdirectories to find the information you need.
+
+- The `contributing/` directory contains information on how to contribute to the project, including guidelines for code contributions and documentation improvements.
+- The `setup/` directory provides instructions for setting up the development environment, including specific instructions for Windows users.
+- The `getting_started/` directory contains basic usage instructions for the `howdoi` command-line tool.
+- The `advanced/` directory includes advanced usage instructions and features of the `howdoi` tool.
+
+Refer to the `mkdocs.yml` configuration file for the complete navigation structure and to ensure proper navigation within the documentation site.
diff --git a/docs/howdoi_advanced_usage.md → docs/advanced/howdoi_advanced_usage.md b/docs/howdoi_advanced_usage.md → docs/advanced/howdoi_advanced_usage.md
diff --git a/docs/contributing.md → docs/contributing/contributing.md b/docs/contributing.md → docs/contributing/contributing.md
@@ -1,3 +1,42 @@
+## Contributing to Howdoi
+
+As beginners, navigating the codebase and finding your way out of the documentation can become difficult. This page will help you understand everything about contributing to howdoi and the best practices in open source as well.
+You can either contribute code to Howdoi (explained on this page) or contribute documentation (explained on next page)
+
+### Setting up the development environment
+
+Follow the page [Setting up the development environment](http://gleitz.github.io/howdoi/development_env/) for setting up the development environment for Howdoi.
+
+### Finding your first issue
+
+- Go to issues in the [howdoi repo](https://github.com/gleitz/howdoi).
+- Find the issues which you might be interested to work on. Or, you can also come up with your own ideas of improving howdoi.
+- After finding the issue you are interested in : If the issue is an existing one, comment on the issue and ask for it to be assigned to you. Or, if the issue is unlisted and new , create a new issue and fill every information needed in the issues template provided by howdoi and ask for it to be assigned to you.
+
+- After receiving confirmation, start working on the issue and whenever and wherever help is needed, comment on the issue itself describing your query in detail.
+- A good guide on how to collaborate efficiently can be found [here](https://lab.github.com/githubtraining/introduction-to-github){:target="\_blank"}.
+
+### Making a Pull request (PR)
+
+- After you have worked on the issue and fixed it, we need to merge it from your forked repository into the howdoi repository. This is done by making a PR.
+- You can search
+  ```
+  howdoi create a pull request on Github
+  ```
+  in your command line and follow the steps written in it.
+- Each PR made should pass all the tests and should not have any flake8 or pylint errors. Github runs tests on each PR but we before that, you should run `python setup.py lint` which will run pylint and flake8.
+
+- Once your commit passes all the tests, make a PR and wait for it to be reviewed and merged.
+
+### Asking for help
+
+At times, help is needed while solving the issue. We recommend the following step for asking for help when you get stuck:
+
+1. Read from howdoi docs and howdoi github to see if your answer has already been answered.
+2. Comment on the issue you are working describing in detail what problems you are facing.
+3. Make sure to write your query in detail and if it is bug, include steps to reproduce it.
+4. If you are not working on any issue and have a question to be answered, open a new issue on Github and wait for a reply on it.
+
 ## General guidelines
 
 Be sure to go through these items before creating a new issue:
@@ -14,9 +53,7 @@ Be sure to go through these items before creating a new issue:
 !!! Note
     Follow Github's [guide to collaborating efficiently](https://lab.github.com/githubtraining/introduction-to-github).
 
-
-
-## Setting up development environment
+### Setting up development environment
 
 Clone the git repository
 ```bash
@@ -34,7 +71,7 @@ Install packages
 $ pip install -r requirements.txt
 ```
 
-## Running howdoi
+### Running howdoi
 
 Run on the command-line
 ```bash
@@ -67,8 +104,7 @@ output = howdoi.howdoi(args)
 !!! attention
     Parsing queries yourself is the older way to pass in queries and may be deprecated in the future. Prefer the first example.
 
-
-## Submitting Pull Requests
+### Submitting Pull Requests
 Before PRs are accepted they must pass all [Travis tests](https://travis-ci.org/gleitz/howdoi) and not have any `flake8` or `pylint` warnings or errors.
 
 #### Testing
@@ -102,6 +138,28 @@ $ pylint *
 !!! tip
     Howdoi uses vanilla configuration files for both linters (`.flake8rc` and `.pylintrc` in the root directory), but with a max line length of 119 characters.
 
+## Contributing to Documentation
+
+If you would like to improve the existing documentation, you can do so by using `mkdocs`. Howdoi uses mkdocs to render its documentation. Steps to contribute to docs:
+
+- Every step from [Contributing to howdoi](http://gleitz.github.io/howdoi/contributing_to_howdoi/) remains the same with additional requirements of installing and building mkdocs.
+- First, install mkdocs by running the following command:
+  ```
+  pip install mkdocs
+  ```
+- You can learn about mkdocs usage from [mkdocs documentation](https://www.mkdocs.org/user-guide/).
+- You can propose your documentation by [creating a new issue](https://github.com/gleitz/howdoi/issues/new/choose).
+- Once approved in the issue, you can create a PR with modifications to the mkdocs markdown.
+- Next, create a new branch and go to the folder `howdoi/docs/` and add a .md file.
+- Go to `mkdocs.yml` and add the name of your added .md file in `nav`
+- To see the changes in your local server, go to your terminal and in this directory run :
+
+```
+   $ mkdocs build
+   $ mkdocs serve
+```
+
+- Once done, make a PR for the same and wait for it to be reviewed.
 
 ## Documentation
 
@@ -111,23 +169,21 @@ To get started building the docs first download `mkdocs`
 $ pip install mkdocs-material markdown-include
 ```
 
-#### Commands
+### Commands
 
 * `python -m mkdocs new [dir-name]` - Create a new project.
 * `python -m mkdocs serve` - Start the live-reloading docs server.
 * `python -m mkdocs build` - Build the documentation site.
 * `python -m mkdocs help` - Print this help message.
 
-
-#### Project layout
+### Project layout
 
     mkdocs.yml    # The configuration file.
     docs/
         index.md  # The documentation homepage.
         ...       # Other markdown pages, images and other files.
 
-
-#### Here are some example alerts you can use
+### Here are some example alerts you can use
 These are from the [Adomonition](https://python-markdown.github.io/extensions/admonition/) extension
 
 !!! attention
@@ -165,7 +221,7 @@ Alternatively you can use the `!!! type "Custom Title"` format to get the correc
 !!! tip "Tip type alert but with a custom title"
     they're good aren't they
 
-#### Include source code in 1 line of code
+### Include source code in 1 line of code
 
 To import code we can use this syntax inside of a code block with the language label:  "{\!path/to/file\!}".
 
@@ -175,7 +231,7 @@ Here's `../howdoi/__init__.py`
 {!../howdoi/__init__.py!}
 ```
 
-#### Here is a choice tab
+### Here is a choice tab
 Proper syntax highlighted code blocks in these don't work the way you'd think and I don't know how to get them to work normally without some extension
 
 === "Python"
@@ -199,7 +255,6 @@ Proper syntax highlighted code blocks in these don't work the way you'd think an
     }
     ```
 
-
 You can include the contents of a file
 ```Python
 {!../howdoi/__init__.py!}

diff --git a/docs/contributing_docs.md b/docs/contributing_docs.md
diff --git a/docs/contributing_to_howdoi.md b/docs/contributing_to_howdoi.md
diff --git a/docs/usage.md → docs/getting_started/usage.md b/docs/usage.md → docs/getting_started/usage.md
diff --git a/docs/development_env.md → docs/setup/development_env.md b/docs/development_env.md → docs/setup/development_env.md
diff --git a/docs/windows-contributing.md → docs/setup/windows-contributing.md b/docs/windows-contributing.md → docs/setup/windows-contributing.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -15,14 +15,13 @@ edit_uri: ""
 nav:
   - howdoi: index.md
   - Introduction: introduction.md
-  - Usage: usage.md
-  - Setting up development environment: development_env.md
-  - Contributing: contributing_to_howdoi.md
-  - Contributing documentation: contributing_docs.md
+  - Usage: getting_started/usage.md
+  - Setting up development environment: setup/development_env.md
+  - Contributing: contributing/contributing.md
   - Extension development: extension_dev.md
-  - Howdoi advanced usage: howdoi_advanced_usage.md
+  - Howdoi advanced usage: advanced/howdoi_advanced_usage.md
   - Troubleshooting: troubleshooting.md
-  - Development for Windows: windows-contributing.md
+  - Development for Windows: setup/windows-contributing.md
 
 markdown_extensions:
   - toc: