From 53ab98f23b3f08465f098d1ac592abe9dad289ac Mon Sep 17 00:00:00 2001 From: Bryce Meyer Date: Thu, 16 Nov 2023 21:28:27 +0100 Subject: [PATCH 1/4] added generation again --- .github/workflows/gh-pages.yml | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index ab7aca0b..79728bdc 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -37,4 +37,24 @@ jobs: uses: actions/upload-artifact@v3 with: name: documentation - path: docs/build + path: docs/generated + + deploy-docs: + name: Deploy Docs + runs-on: ubuntu-latest + # Only run if merging a PR into main + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: build-docs + steps: + - uses: actions/checkout@v4 + - name: Download Docs Artifact + uses: actions/download-artifact@v3 + with: + name: documentation + path: docs/generated + - name: Upload to GitHub Pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs/generated + clean-exclude: | + *.*.*/ From 5826f83a40c80028d45ce42a1b8a1f6fe2370d74 Mon Sep 17 00:00:00 2001 From: Bryce Meyer Date: Fri, 1 Dec 2023 18:46:20 +0100 Subject: [PATCH 2/4] added faq pages --- docs/content/SUMMARY.md | 3 ++- docs/content/faq/SUMMARY.md | 7 +++++++ docs/content/faq/abstract_structure.md | 1 + docs/content/faq/begin_collaborating.md | 1 + docs/content/faq/bypassing_lint.md | 1 + docs/content/faq/design_structure.md | 1 + docs/content/faq/entry_point.md | 1 + docs/content/faq/index.md | 7 +++++++ docs/content/faq/missing_function_documentation.md | 1 + docs/content/faq/proposing_major_changes.md | 0 10 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 docs/content/faq/SUMMARY.md create mode 100644 docs/content/faq/abstract_structure.md create mode 100644 docs/content/faq/begin_collaborating.md create mode 100644 docs/content/faq/bypassing_lint.md create mode 100644 docs/content/faq/design_structure.md create mode 100644 docs/content/faq/entry_point.md create mode 100644 docs/content/faq/index.md create mode 100644 docs/content/faq/missing_function_documentation.md create mode 100644 docs/content/faq/proposing_major_changes.md diff --git a/docs/content/SUMMARY.md b/docs/content/SUMMARY.md index 03e1fbb2..0bacebf5 100644 --- a/docs/content/SUMMARY.md +++ b/docs/content/SUMMARY.md @@ -2,5 +2,6 @@ * [Home](index.md) * [Demo](demo.ipynb) * [Reference](reference/) +* [FAQ](faq/) * [Contributing](contributing.md) -* [Citation](citation.md) \ No newline at end of file +* [Citation](citation.md) diff --git a/docs/content/faq/SUMMARY.md b/docs/content/faq/SUMMARY.md new file mode 100644 index 00000000..5831c38b --- /dev/null +++ b/docs/content/faq/SUMMARY.md @@ -0,0 +1,7 @@ +* [What is the top-level interface?/What's the main entry point?](entry_point.md) +* [How do I get past the linting checks?](bypassing_lint.md) +* [How do all the abstract classes fit together?](abstract_structure.md) +* [How should I go about proposing a major change?](proposing_major_changes.md) +* [How should I approach collaborating on this?](begin_collaborating.md) +* [What do I do if I find a function without proper documentation?](missing_function_documentation.md) +* [What is the purpose of the design philosophy behind this code base?](design_structure.md) diff --git a/docs/content/faq/abstract_structure.md b/docs/content/faq/abstract_structure.md new file mode 100644 index 00000000..0807a8e9 --- /dev/null +++ b/docs/content/faq/abstract_structure.md @@ -0,0 +1 @@ +# How do all the abstract classes fit together? diff --git a/docs/content/faq/begin_collaborating.md b/docs/content/faq/begin_collaborating.md new file mode 100644 index 00000000..78c9678e --- /dev/null +++ b/docs/content/faq/begin_collaborating.md @@ -0,0 +1 @@ +# How should I approach collaborating on this? diff --git a/docs/content/faq/bypassing_lint.md b/docs/content/faq/bypassing_lint.md new file mode 100644 index 00000000..b2044412 --- /dev/null +++ b/docs/content/faq/bypassing_lint.md @@ -0,0 +1 @@ +# How do I get past the linting checks? diff --git a/docs/content/faq/design_structure.md b/docs/content/faq/design_structure.md new file mode 100644 index 00000000..4427aa00 --- /dev/null +++ b/docs/content/faq/design_structure.md @@ -0,0 +1 @@ +# What is the purpose of the design philosophy behind this code base? diff --git a/docs/content/faq/entry_point.md b/docs/content/faq/entry_point.md new file mode 100644 index 00000000..46f8f1cb --- /dev/null +++ b/docs/content/faq/entry_point.md @@ -0,0 +1 @@ +# What is the top-level interface?/What's the main entry point? diff --git a/docs/content/faq/index.md b/docs/content/faq/index.md new file mode 100644 index 00000000..3e8be923 --- /dev/null +++ b/docs/content/faq/index.md @@ -0,0 +1,7 @@ +# FAQ + +Use this for guide as a reference for any questions that may come up while coding in this project. A +lot of questions that have come up about tooling, and how to configure it have been answered here. +If anything comes up while working on the project, please do not hesitate to ask in the Open Source +Mechanistic Interpretabiliy slack, or in a GitHub issue. If it came up while you were working, then +it may come up for someone else, so adding it here can always be helpful. diff --git a/docs/content/faq/missing_function_documentation.md b/docs/content/faq/missing_function_documentation.md new file mode 100644 index 00000000..46071a18 --- /dev/null +++ b/docs/content/faq/missing_function_documentation.md @@ -0,0 +1 @@ +# What do I do if I find a function without proper documentation? diff --git a/docs/content/faq/proposing_major_changes.md b/docs/content/faq/proposing_major_changes.md new file mode 100644 index 00000000..e69de29b From 8453ac3d9217cd3b4918b2d5615fe47c2b37d5f5 Mon Sep 17 00:00:00 2001 From: Bryce Meyer Date: Tue, 5 Dec 2023 22:12:59 +0100 Subject: [PATCH 3/4] added header --- docs/content/faq/proposing_major_changes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content/faq/proposing_major_changes.md b/docs/content/faq/proposing_major_changes.md index e69de29b..2e42bd05 100644 --- a/docs/content/faq/proposing_major_changes.md +++ b/docs/content/faq/proposing_major_changes.md @@ -0,0 +1 @@ +# How should I go about proposing a major change? From 00411ad96eb508ec3bb0e9e2f8505a01e1f0b257 Mon Sep 17 00:00:00 2001 From: Bryce Meyer Date: Thu, 7 Dec 2023 23:58:37 +0100 Subject: [PATCH 4/4] finished bypassing lint doc --- docs/content/faq/bypassing_lint.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/content/faq/bypassing_lint.md b/docs/content/faq/bypassing_lint.md index b2044412..cef34796 100644 --- a/docs/content/faq/bypassing_lint.md +++ b/docs/content/faq/bypassing_lint.md @@ -1 +1,27 @@ # How do I get past the linting checks? + +The first thing you should do is install the visual studio code [Ruff +plugin](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff). This plugin is +going to solve the vast majority of issues you may come across while working on this project. Most +common issues the linter finds will be automatically fixed when saving files with this plugin. + +Some common issues caught by the lint checks cannot be automatically fixed. e.g. unknown types from +an outside package, print statements, commented out lines of code, etc... When encountering some of +these issues, there are a few options. + +If you are in the middle of working on something, and you simply want to commit your changes in +order to finish what you are doing later, you can edit the file `pyproject.toml` to allow you to +commit your files while temporarily ignoring lint. To do this you want to add an entry to the block +`tool.ruff.lint.per-file-ignores` with your file name as the key, and a list of any lint codes you want to +ignore within those files. Please note that you most likely will need to remove these rules before +submitting a pull request. In almost all cases there is a more permanent solution to skipping lint, +and adding rules to your working files should only be a temporary solution to allow the lint to get +out of your way while developing a work in progress. There are situations where lint needs to be +skipped in this way, but those are few and far between. Most of those situations have also already +been addressed. + +In cases where you may need a more permanent bypass of lint checks, you can create case exceptions +for individual lines see [docs for examples](https://docs.astral.sh/ruff/tutorial/#ignoring-errors). +Common cases where this is necessary is when a dependency has poor typing, and the linter complains +about references to those components in your code. More often than not, it is not necessary to skip +lines of files, and this should only be done as a last resort.