From cbda6f5eb395b5f52acefbcaa43e3e8b907018a1 Mon Sep 17 00:00:00 2001 From: k4lizen <124312252+k4lizen@users.noreply.github.com> Date: Mon, 26 May 2025 12:22:13 +0200 Subject: [PATCH] order the contributing documentation properly (#3013) --- docs/contributing/.nav.yml | 11 +++++++++++ docs/contributing/adding-a-command.md | 6 +++--- docs/contributing/{2-dev-notes.md => dev-notes.md} | 0 docs/contributing/index.md | 6 +++--- .../{1-setup-pwndbg-dev.md => setup-pwndbg-dev.md} | 0 .../{3-writing-tests.md => writing-tests.md} | 0 docs/setup.md | 2 +- 7 files changed, 18 insertions(+), 7 deletions(-) create mode 100644 docs/contributing/.nav.yml rename docs/contributing/{2-dev-notes.md => dev-notes.md} (100%) rename docs/contributing/{1-setup-pwndbg-dev.md => setup-pwndbg-dev.md} (100%) rename docs/contributing/{3-writing-tests.md => writing-tests.md} (100%) diff --git a/docs/contributing/.nav.yml b/docs/contributing/.nav.yml new file mode 100644 index 000000000..d95726013 --- /dev/null +++ b/docs/contributing/.nav.yml @@ -0,0 +1,11 @@ +# https://lukasgeiter.github.io/mkdocs-awesome-nav/ +# Allows us to specify the order of these pages. +nav: + - index.md + - setup-pwndbg-dev.md + - dev-notes.md + - writing-tests.md + - adding-a-command.md + - adding-a-parameter.md + - improving-annotations.md + - making-a-gif.md diff --git a/docs/contributing/adding-a-command.md b/docs/contributing/adding-a-command.md index 903f4fe48..cf77c8682 100644 --- a/docs/contributing/adding-a-command.md +++ b/docs/contributing/adding-a-command.md @@ -13,7 +13,7 @@ def my_command(arg: str) -> None: """Print the argument""" print(f"Argument is {arg}") ``` -Next, import this file in the `load_commands` function in `pwndbg/commands/__init__.py`. +Next, import this file in the `load_commands` function in `pwndbg/commands/__init__.py`. That's all you need to get it working! ```text @@ -58,7 +58,7 @@ We are using [`argparse.ArgumentParser`](https://docs.python.org/3/library/argpa parser = argparse.ArgumentParser(description="Modify the flags register.") parser.add_argument( - "flag", + "flag", type=str, help="Flag for which you want to change the value" ) @@ -184,4 +184,4 @@ Feel free to add more of these decorators yourself! Another very important one is `OnlyWithArch`, defined in `pwndbg/aglib/proc.py`. Does your command work on all architectures? If not, make sure to specify this decorator and pass in the architectures which you do support. ## Actually implementing the command -There is no single right way to do it. You will want to read the source of some similar commands and see how they work. Check out the [general developer notes](2-dev-notes.md), and feel free to ask a question on the [discord server](https://discord.gg/x47DssnGwm). Good luck! \ No newline at end of file +There is no single right way to do it. You will want to read the source of some similar commands and see how they work. Check out the [general developer notes](dev-notes.md), and feel free to ask a question on the [discord server](https://discord.gg/x47DssnGwm). Good luck! diff --git a/docs/contributing/2-dev-notes.md b/docs/contributing/dev-notes.md similarity index 100% rename from docs/contributing/2-dev-notes.md rename to docs/contributing/dev-notes.md diff --git a/docs/contributing/index.md b/docs/contributing/index.md index e2d9ee79c..b91869909 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -5,7 +5,7 @@ Thank you for your interest in contributing to pwndbg! Note that while it is recommended that your pull request (PR) links to an issue (which can be used for discussing the bug / feature), you do not need to be assigned to it - just create the PR and it will be reviewed. -To start, [install pwndbg from source and set it up for development](1-setup-pwndbg-dev.md). +To start, [install pwndbg from source and set it up for development](setup-pwndbg-dev.md). For common tasks see: + [Adding a command](adding-a-command.md) @@ -14,7 +14,7 @@ For common tasks see: Regardless of the contents of your PR, you will need to [lint](#linting) and [test](#running-tests) your code so make sure to read those sections. It is also likely you will need to [update the documentation](#updating-documentation). -Read [General developer notes](2-dev-notes.md) to get more familiar with the various systems in place in pwndbg. If you have any questions don't hesitate to ask us on our [discord server](https://discord.gg/x47DssnGwm)! +Read [General developer notes](dev-notes.md) to get more familiar with the various systems in place in pwndbg. If you have any questions don't hesitate to ask us on our [discord server](https://discord.gg/x47DssnGwm)! ## Linting The `lint.sh` script runs isort, ruff, shfmt, and vermin. isort and ruff (mostly) are able to automatically fix any issues they detect. You may apply all available fixes by running ```{.bash .copy} @@ -27,7 +27,7 @@ When submitting a PR, the continuous integration (CI) job defined in `.github/wo It is recommended to enable the pre-push git hook to run the lint if you haven't already done so. You may re-run `./setup-dev.sh` to set it. ## Running tests -Your PR will not be merged without passing the testing CI. Moreover, it is highly recommended you write a new test or update an existing test whenever adding new functionality to pwndbg. To see how to do this, check out [Writing tests](3-writing-tests.md). +Your PR will not be merged without passing the testing CI. Moreover, it is highly recommended you write a new test or update an existing test whenever adding new functionality to pwndbg. To see how to do this, check out [Writing tests](writing-tests.md). To run the tests in the same environment as the testing CI, you can use the following docker commands. ```{.bash .copy} diff --git a/docs/contributing/1-setup-pwndbg-dev.md b/docs/contributing/setup-pwndbg-dev.md similarity index 100% rename from docs/contributing/1-setup-pwndbg-dev.md rename to docs/contributing/setup-pwndbg-dev.md diff --git a/docs/contributing/3-writing-tests.md b/docs/contributing/writing-tests.md similarity index 100% rename from docs/contributing/3-writing-tests.md rename to docs/contributing/writing-tests.md diff --git a/docs/setup.md b/docs/setup.md index 636e3ebed..93cc2dad9 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -77,4 +77,4 @@ or depending on which version you installed. You may add the appropriate file to your shell's PATH. ## Installing from source -See [contributing/Installing pwndbg from source](contributing/1-setup-pwndbg-dev.md#installing-pwndbg-from-source), you do not need the "The development environment" section. +See [contributing/Installing pwndbg from source](contributing/setup-pwndbg-dev.md#installing-pwndbg-from-source), you do not need the "The development environment" section.