Содержание:

• Обзор
• Методы экземпляра
• Основные фильтры
• Пользовательские фильтры
  • CleanHtmlFilter
  • EntriesFilter

Обзор

Фильтры используют библиотеку HTML::Pipeline. Они принимают строку HTML или узел Nokogiri в качестве входных данных, опционально выполняют модификации и/или извлекают информацию из него, а затем выводят результат. Вместе они образуют конвейер, где каждый фильтр передаёт свой вывод на вход следующего фильтра. Каждая страница документации проходит через этот конвейер перед копированием в локальную файловую систему.

Фильтры являются подклассами класса Docs::Filter и требуют наличия метода call. Базовая реализация выглядит следующим образом:

module Docs
  class CustomFilter < Filter
    def call
      doc
    end
  end
end

Фильтры, которые манипулируют объектом узла Nokogiri (doc и связанные методы), являются фильтрами HTML и не должны манипулировать строкой HTML (html). И наоборот, фильтры, которые манипулируют строковым представлением документа, являются текстовыми фильтрами и не должны манипулировать объектом узла Nokogiri. Эти два типа разделены на две стопки внутри скребков. Затем эти стопки объединяются в конвейер, который вызывает фильтры HTML перед текстовыми фильтрами (подробнее здесь). Это делается для того, чтобы избежать многократного анализа документа.

Метод call должен возвращать либо doc, либо html, в зависимости от типа фильтра.

Методы экземпляра

• doc [Nokogiri::XML::Node] — представление контейнера Nokogiri. См. документацию API Nokogiri для получения списка доступных методов.
• html [String] — строковое представление элемента контейнера.
• context [Hash] (замороженный) — параметры скребка вместе с несколькими дополнительными ключами: :base_url, :root_url, :root_page и :url.
• result [Hash] — используется для хранения метаданных страницы и передачи информации обратно скребку. Возможные ключи: — :path — нормализованный путь страницы; — :store_path — путь, по которому будет сохранена страница (равен :path с .html в конце); — :internal_urls — список различных внутренних URL-адресов, найденных на странице; — :entries — объекты Entry, которые необходимо добавить в индекс.
• css, at_css, xpath, at_xpath — ярлыки для doc.css, doc.xpath и т. д.
• base_url, current_url, root_url [Docs::URL] — ярлыки для context[:base_url], context[:url] и context[:root_url] соответственно.
• root_path [String] — ярлык для context[:root_path].
• subpath [String] — подпуть от базового URL текущего URL. Пример: если base_url равен example.com/docs, а current_url равен example.com/docs/file?raw, возвращаемое значение равно /file.
• slug [String] — subpath, удалённый из любого начального слэша или расширения .html. Пример: если subpath равен /dir/file.html, возвращаемое значение — dir/file.
• root_page? [Boolean] — возвращает true, если текущая страница является корневой страницей.
• initial_page? [Boolean] — возвращает true, если текущая страница является корневой или её подпуть является одним из начальных путей скребка.

Основные фильтры

• ContainerFilter — изменяет корневой узел документа (удаляет всё снаружи).
• CleanHtmlFilter — удаляет комментарии HTML, <script>, <style> и т.д.
• NormalizeUrlsFilter — заменяет все URL-адреса их полностью квалифицированными аналогами. Перевод текста на русский язык:

InternalUrlsFilter — обнаруживает внутренние URL-адреса (те, которые нужно очистить) и заменяет их на их неквалифицированные, относительные аналоги.

• NormalizePathsFilter — делает внутренние пути согласованными (например, всегда заканчиваются на .html).
• CleanLocalUrlsFilter — удаляет ссылки, фреймы и изображения, указывающие на localhost (FileScraper только).
• InnerHtmlFilter — преобразует документ в строку.
• CleanTextFilter — удаляет пустые узлы.
• AttributionFilter — добавляет информацию о лицензии и ссылку на исходный документ.
• TitleFilter — предваряет документ заголовком (по умолчанию отключён).
• EntriesFilter — абстрактный фильтр для извлечения метаданных страницы.

Пользовательские фильтры

Скрейперы могут иметь любое количество пользовательских фильтров, но требуют как минимум двух, описанных ниже.

Примечание: фильтры находятся в каталоге lib/docs/filters. Имя класса должно быть эквивалентом имени файла в CamelCase (см. документацию по API).

CleanHtmlFilter

Фильтр CleanHtml предназначен для очистки HTML-разметки там, где это необходимо, и удаления всего лишнего или несущественного. В конце должен остаться только основной документ.

Множество jQuery-подобных методов Nokogiri упрощают поиск и изменение элементов — см. документы API.

Вот пример реализации, охватывающий наиболее распространённые случаи использования:

module Docs
  class MyScraper
    class CleanHtmlFilter < Filter
      def call
        css('hr').remove
        css('#changelog').remove if root_page?

        # Установить атрибуты id для <h3> вместо пустого <a>
        css('h3').each do |node|
          node['id'] = node.at_css('a')['id']
        end

        # Сделать правильные заголовки таблиц
        css('td.header').each do |node|
          node.name = 'th'
        end

        # Удалить выделение кода
        css('pre').each do |node|
          node.content = node.content
        end

        doc
      end
    end
  end
end

Примечания:

• Пустые элементы будут автоматически удалены основным фильтром CleanTextFilter позже при выполнении конвейера.
• Хотя цель состоит в том, чтобы получить чистую версию страницы, старайтесь свести количество изменений к минимуму, чтобы упростить обслуживание кода. Пользовательский CSS является предпочтительным способом нормализации страниц (за исключением скрытия содержимого, которое всегда должно выполняться путём удаления разметки).
• Постарайтесь максимально документировать поведение фильтра, особенно изменения, которые применяются только к подмножеству страниц. Это облегчит обновление документации.

EntriesFilter

Фильтр Entries отвечает за извлечение метаданных страницы, представленных набором элементов, каждый из которых имеет имя, тип и путь.

Для представления метаданных используются следующие две модели:

• Entry(name, type, path)
• Type(name, slug, count)

Каждый скрейпер должен реализовать свой собственный фильтр Entries, создав подкласс класса Docs::EntriesFilter. Базовый класс уже реализует... ``` return [[Home]]

**Возврат значения [[Home]].**