diff --git a/docs/contribute.dir/develop.dir/documentation.rst b/docs/contribute.dir/develop.dir/documentation.rst deleted file mode 100644 index e32acbb4..00000000 --- a/docs/contribute.dir/develop.dir/documentation.rst +++ /dev/null @@ -1,18 +0,0 @@ -Documentation -============= - -Sphinx is used to pull richly formatted comments out of code, merge them with hand-written documentation and render it -in HTML and other formats. - -To build the docs, simply run `$ fab -H localhost build_docs` once you have set up Fabric. - -Restructured Text (RsT) vs MarkDown (md) ----------------------------------------- - -There's much on the internet about this. Suffice to say RsT_ is preferred for Python documentation while md is preferred for web markup or for certain other languages. - -.. _Rst: [http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html]` style is preferred, - -`md` files can also be incorporated by using mdinclude directives in the indices. They are translated to RsT before rendering to the various formats. Headers are translated as a hard-coded level `(H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #`. This represents a small consideration for both styles. If markup is not translated to rst well enough, switch to rst. - - diff --git a/docs/contribute.dir/develop.dir/fabric.rst b/docs/contribute.dir/develop.dir/fabric.rst deleted file mode 100644 index 8003f33a..00000000 --- a/docs/contribute.dir/develop.dir/fabric.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. mdinclude:: ../../../fabfile/README.md - diff --git a/docs/contribute.dir/develop.dir/opsec.rst b/docs/contribute.dir/develop.dir/opsec.rst deleted file mode 100644 index 1af43668..00000000 --- a/docs/contribute.dir/develop.dir/opsec.rst +++ /dev/null @@ -1,38 +0,0 @@ -Operational Security -==================== - -Bitmessage has many features that are designed to protect your anonymity during normal use. There are other things that you must or should do if you value your anonymity. - -Castles in the sand -------------------- - -You cannot build a strong castle on unstable foundations. If your operating system is not wholly owned by you then it is impossible to make guarantees about an application. - - * Carefully choose your operating system - * Ensure your operating system is up to date - * Ensure any dependencies and requirements are up to date - -Extrordinary claims require extrordinary evidence -------------------------------------------------- - -If we are to make bold claims about protecting your privacy we should demonstrate this by strong actions. - -- PGP signed commits -- looking to audit -- warrant canary - -Digital footprint ------------------- - -Your internet use can reveal metadata you wouldn't expect. This can be connected with other information about you if you're not careful. - - * Use separate addresses for different purposes - * Don't make the same mistakes all the time - * Your language use is unique. The more you type, the more you fingerprint yourself. The words you know and use often vs the words you don't know or use often. - -Cleaning history ----------------- - - * Tell your browser not to store BitMessage addresses - * Microsoft Office seems to offer the ability to define sensitive informations types. If browsers don't already they may in the future. Consider adding `BM-\w{x..y}`. - diff --git a/docs/contribute.dir/develop.dir/overview.rst b/docs/contribute.dir/develop.dir/overview.rst deleted file mode 100644 index 8bbc8299..00000000 --- a/docs/contribute.dir/develop.dir/overview.rst +++ /dev/null @@ -1,88 +0,0 @@ -Developing -========== - -Devops tasks ------------- - -Bitmessage makes use of fabric_ to define tasks such as building documentation or running checks and tests on the code. If you can install - -.. _fabric: https://fabfile.org - -Code style and linters ----------------------- - -We aim to be PEP8 compliant but we recognize that we have a long way still to go. Currently we have style and lint exceptions specified at the most specific place we can. We are ignoring certain issues project-wide in order to avoid alert-blindness, avoid style and lint regressions and to allow continuous integration to hook into the output from the tools. While it is hoped that all new changes pass the checks, fixing some existing violations are mini-projects in themselves. Current thinking on ignorable violations is reflected in the options and comments in setup.cfg. Module and line-level lint warnings represent refactoring opportunities. - -Pull requests -------------- - -There is a template at PULL_REQUEST_TEMPLATE.md that appears in the pull-request description. Please replace this text with something appropriate to your changes based on the ideas in the template. - -Bike-shedding -------------- - -Beyond having well-documented, Pythonic code with static analysis tool checks, extensive test coverage and powerful devops tools, what else can we have? Without violating any linters there is room for making arbitrary decisions solely for the sake of project consistency. These are the stuff of the pedant's PR comments. Rather than have such conversations in PR comments, we can lay out the result of discussion here. - -I'm putting up a strawman for each topic here, mostly based on my memory of reading related Stack Overflow articles etc. If contributors feel strongly (and we don't have anything better to do) then maybe we can convince each other to update this section. - -Trailing vs hanging braces - Data - Hanging closing brace is preferred, trailing commas always to help reduce churn in diffs - Function, class, method args - Inline until line-length, then style as per data - Nesting - Functions - Short: group hanging close parentheses - Long: one closing parentheses per line - -Single vs double quotes - Single quotes are preferred; less strain on the hands, eyes - - Double quotes are only better so as to contain single quotes, but we want to contain doubles as often - -Line continuation - Implicit parentheses continuation is preferred - -British vs American spelling - We should be consistent, it looks like we have American to British at approx 140 to 60 in the code. There's not enough occurrences that we couldn't be consistent one way or the other. It breaks my heart that British spelling could lose this one but I'm happy to 'z' things up for the sake of consistency. So I put forward British to be preferred. Either that strawman wins out, or I incite interest in ~bike-shedding~ guiding the direction of this crucial topic from others. - -Dependency graph ----------------- - -These images are not very useful right now but the aim is to tweak the settings of one or more of them to be informative, and/or divide them up into smaller graphs. - -To re-build them, run `fab build_docs:dep_graphs=true`. Note that the dot graph takes a lot of time. - -.. figure:: ../../../../_static/deps-neato.png - :alt: neato graph of dependencies - :width: 100 pc - - :index:`Neato` graph of dependencies - -.. figure:: ../../../../_static/deps-sfdp.png - :alt: SFDP graph of dependencies - :width: 100 pc - - :index:`SFDP` graph of dependencies - -.. figure:: ../../../../_static/deps-dot.png - :alt: Dot graph of dependencies - :width: 100 pc - - :index:`Dot` graph of dependencies - -Key management --------------- - -Nitro key -^^^^^^^^^ - -Regular contributors are enouraged to take further steps to protect their key and the Nitro Key (Start) is recommended by the BitMessage project for this purpose. - -Debian-quirks -~~~~~~~~~~~~~ - -Stretch makes use of the directory ~/.gnupg/private-keys-v1.d/ to store the private keys. This simplifies some steps of the Nitro Key instructions. See step 5 of Debian's subkeys_ wiki page - -.. _subkeys: https://wiki.debian.org/Subkeys - diff --git a/docs/contribute.dir/develop.dir/testing.rst b/docs/contribute.dir/develop.dir/testing.rst deleted file mode 100644 index 2947c7d6..00000000 --- a/docs/contribute.dir/develop.dir/testing.rst +++ /dev/null @@ -1,4 +0,0 @@ -Testing -======= - -Currently there is a Travis job somewhere which runs python setup.py test. This doesn't find any tests when run locally for some reason. diff --git a/docs/contribute.dir/develop.dir/todo.rst b/docs/contribute.dir/develop.dir/todo.rst deleted file mode 100644 index 34f71f42..00000000 --- a/docs/contribute.dir/develop.dir/todo.rst +++ /dev/null @@ -1,4 +0,0 @@ -TODO list -========= - -.. todolist:: diff --git a/docs/contribute.dir/develop.rst b/docs/contribute.dir/develop.rst deleted file mode 100644 index e5563eb2..00000000 --- a/docs/contribute.dir/develop.rst +++ /dev/null @@ -1,8 +0,0 @@ -Developing -========== - -.. toctree:: - :maxdepth: 2 - :glob: - - develop.dir/* diff --git a/docs/contribute.dir/processes.rst b/docs/contribute.dir/processes.rst deleted file mode 100644 index eb913325..00000000 --- a/docs/contribute.dir/processes.rst +++ /dev/null @@ -1,28 +0,0 @@ -Processes -========= - -In order to keep the Bitmessage project running, the team runs a number of systems and accounts that form the -development pipeline and continuous delivery process. We are always striving to improve this process. Towards -that end it is documented here. - - -Project website ---------------- - -The bitmessage website_ - -Github ------- - -Our official Github_ account is Bitmessage. Our issue tracker is here as well. - - -BitMessage ----------- - -We eat our own dog food! You can send us bug reports via the [chan] bitmessage BM-2cWy7cvHoq3f1rYMerRJp8PT653jjSuEdY - - -.. _website: https://bitmessage.org -.. _Github: https://github.com/Bitmessage/PyBitmessage - diff --git a/docs/contribute.rst b/docs/contribute.rst deleted file mode 100644 index 7c79e22c..00000000 --- a/docs/contribute.rst +++ /dev/null @@ -1,25 +0,0 @@ -Contributing -============ - -.. toctree:: - :maxdepth: 2 - :glob: - - contribute.dir/* - - -- Report_ -- Develop_(develop) -- Translate_ -- Donate_ -- Fork the code and open a PR_ on github -- Search the `issue tracker` on github or open a new issue -- Send bug report to the chan - -.. _Report: https://github.com/Bitmessage/PyBitmessage/issues -.. _Develop: https://github.com/Bitmessage/PyBitmessage -.. _Translate: https://www.transifex.com/bitmessage-project/pybitmessage/ -.. _Donate: https://tip4commit.com/github/Bitmessage/PyBitmessage -.. _PR: https://github.com/Bitmessage/PyBitmessage/pulls -.. _`issue tracker`: https://github.com/Bitmessage/PyBitmessage/issues - contributing/* diff --git a/docs/index.rst b/docs/index.rst index cc8c9523..5e8a1c1a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,13 +7,6 @@ Documentation autodoc/pybitmessage -Legacy pages ------------- -.. toctree:: - :maxdepth: 2 - - usage - contribute Indices and tables ------------------ diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index cf745121..00000000 --- a/docs/usage.rst +++ /dev/null @@ -1,21 +0,0 @@ -Usage -===== - -GUI ---- - -Bitmessage has a PyQT GUI_ - -CLI ---- - -Bitmessage has a CLI_ - -API ---- - -Bitmessage has an XML-RPC API_ - -.. _GUI: https://bitmessage.org/wiki/PyBitmessage_Help -.. _CLI: https://bitmessage.org/wiki/PyBitmessage_Help -.. _API: https://bitmessage.org/wiki/API_Reference